ADR-002 — Chatwoot como Plataforma de Atendimento

Data: 2026-04
Status: Ativo

Contexto

O CRM precisava de uma plataforma de atendimento ao cliente (inbox) para WhatsApp. As opções eram:

1. Construir inbox próprio dentro do CRM
2. Usar plataforma de terceiros

Um inbox customizado foi iniciado (modules/inbox/) mas se mostrou muito trabalhoso para replicar features básicas de atendimento.

Alternativas consideradas

Alternativa	Motivo de descarte
Inbox próprio	Muito trabalho para replicar: histórico, atribuição, SLA, relatórios, notificações
Zendesk	SaaS caro, não self-hosted, difícil integrar webhook WhatsApp
Intercom	Similar ao Zendesk — SaaS, caro
Freshdesk	SaaS, limitações de integração WhatsApp
Chatwoot	Open source, self-hosted, API completa, suporte nativo a WhatsApp — escolhido

Decisão

Chatwoot self-hosted como plataforma de atendimento. O inbox customizado do CRM (modules/inbox/) foi descontinuado.

Integração via:

• API REST do Chatwoot para criar conversas, enviar mensagens
• Webhooks do Chatwoot para receber eventos de conversa
• Acesso direto ao banco de dados do Chatwoot para operações que a API não suporta

Consequências

Positivas:

• Atendentes têm interface madura com histórico, notas internas, SLA
• Integração WhatsApp nativa no Chatwoot
• Self-hosted — dados não saem do servidor
• API bem documentada e estável

Negativas:

• Dependência de instância Chatwoot separada (mais um serviço para manter)
• Acesso direto ao banco do Chatwoot é frágil (pode quebrar com upgrades)
• Sync entre CRM ↔ Chatwoot adiciona complexidade (SyncEvent, SyncFailure)

Arquitetura de integração

n8n workflow "Chatwoot Event Router":
  Chatwoot webhook → n8n → CRM API
  
CRM → Chatwoot API:
  ChatwootApiService (REST)
  ChatwootDbService (PostgreSQL direto)

Referências de implementação

• backend/src/modules/chatwoot/
• backend/src/modules/chatwoot/chatwoot-api.service.ts
• backend/src/modules/chatwoot/chatwoot-db.service.ts