Chatwoot — Atendimento ao Cliente

O Chatwoot é a plataforma de atendimento ao cliente. É self-hosted (rodando na infraestrutura da organização, não no SaaS público). O CRM integra com ele via API REST e acesso direto ao banco de dados.

Papel no sistema

• Inbox (caixas): Cada loja tem um inbox no Chatwoot para atendimento WhatsApp
• Conversas: Mensagens dos clientes chegam ao Chatwoot para os atendentes
• Pesquisas: Survey de satisfação integrada ao fechar conversa
• Roteamento: CRM roteia novos clientes para o inbox correto

Configuração

Armazenada em ChatwootConfig por organização:

Campo	Descrição
instanceUrl	URL da instância (https://chatwoot.galdix.com.br)
apiKey	Chave de API do Chatwoot (criptografada AES-256-GCM)
accountId	ID da conta no Chatwoot
chatwootInboxId	ID do inbox por loja (em StoreWhatsappNumber)

Modos de integração

1. Modo Evolution (QR Code)

Cada loja tem um número WhatsApp próprio conectado via Evolution API. O Chatwoot recebe as mensagens diretamente da instância Evolution.

2. Modo Meta Cloud (WABA)

Um número WABA central recebe todas as mensagens. O CRM roteia para o inbox do Chatwoot da loja correta baseado na loja preferida do cliente.

Comunicação CRM → Chatwoot

Via API REST

O ChatwootApiService usa a API do Chatwoot para:

// Criar/buscar conversa de um cliente
POST /api/v1/accounts/{accountId}/conversations

// Enviar mensagem para uma conversa
POST /api/v1/accounts/{accountId}/conversations/{id}/messages

// Resolver/reabrir conversa
PATCH /api/v1/accounts/{accountId}/conversations/{id}

// Criar inbox para uma loja
POST /api/v1/accounts/{accountId}/inboxes

// Listar inboxes
GET /api/v1/accounts/{accountId}/inboxes

Via banco de dados (direto)

O ChatwootDbService acessa o banco do Chatwoot diretamente (via conexão PostgreSQL separada) para operações que a API não suporta ou que seriam lentas:

• Buscar wamId de mensagens específicas para reconciliação
• Consultar status de conversas em lote
• Buscar dados de atendentes

Webhooks Chatwoot → CRM

O Chatwoot envia webhooks para POST /webhooks/chatwoot em eventos de conversa.

Verificação: Header X-Chatwoot-Delivery usado como dedup UUID (tabela SyncEvent).

Eventos tratados:

Evento	Ação
message_created	Reconciliar wamId com WhatsappMessage
message_updated	Atualizar status de leitura
conversation_resolved	Registrar resolvedAt + disparar survey se configurado
conversation_reopened	Reabrir conversa no banco CRM

Mensagens configuráveis

Via ChatwootConfig, o admin pode personalizar as mensagens automáticas. Todas suportam variáveis:

• — nome da loja selecionada
• — telefone do cliente
• — nome do cliente
• — nome do vendedor

Mensagem	Campo	Quando é enviada
Handoff	handoffMessage	Ao transferir para atendente humano
Saudação da loja	storeGreetingMessage	Após seleção de loja
Menu	menuMessage	Menu de seleção de loja
Conversa ativa	activeConversationMessage	Se já há conversa aberta
Conectando	connectingMessage	Enquanto busca atendente
Fechamento por horário	closedMessage	Fora do horário comercial

Roteamento de inbox

Ver Regras de Caixas para a lógica completa de roteamento de mensagens para inboxes.

Redis keys do Chatwoot

Key	TTL	Descrição
chatwoot:pending:{phone}	5 min	Dedup de mensagem em processamento
chatwoot:inbox:{storeId}	60s	Cache do inbox ID por loja
conv:redirect:{phone}	—	Rastreia redirect de campanha ativo