API de WhatsApp para Chatwoot

O que dá para fazer com Chatwoot e WhatsApp

• Caixa compartilhada

  Várias pessoas atendendo o mesmo número, cada conversa com responsável e histórico.

• Bot antes do humano

  Um fluxo automático responde o básico e passa para a fila do Chatwoot quando não resolve.

• Aviso ativo com resposta no lugar certo

  O sistema dispara a mensagem pelo Zapixo, e a resposta do cliente cai na conversa dele no Chatwoot.

• Métrica de atendimento

  Tempo de primeira resposta e volume por agente saem dos relatórios do próprio Chatwoot.

Enviar mensagens pelo Chatwoot

1. 1

   Crie uma caixa de entrada do tipo API

   No Chatwoot, em Configurações › Caixas de entrada, adicione uma caixa do tipo API. No campo de webhook, coloque a URL da sua ponte: é para lá que o Chatwoot manda cada mensagem criada nas conversas dessa caixa.

2. 2

   Filtre o que sai

   O Chatwoot avisa no evento message_created a cada mensagem, inclusive as que a própria ponte criou. Mande ao WhatsApp só quando message_type for outgoing e private for false. Nota privada é conversa interna da equipe e não pode chegar ao cliente.

3. 3

   Envie pelo Zapixo

   Com o número da conversa em mãos, a ponte chama o Zapixo com o content da mensagem do agente:

   POST https://zapixo.com.br/api/v1/messages/text
   Authorization: Bearer zpx_...
   Content-Type: application/json
   
   {
     "instance": "suporte",
     "number": "5511999999999",
     "text": "Seu pedido saiu para entrega hoje de manhã."
   }

4. 4

   Guarde o vínculo entre conversa e número

   A ponte precisa saber qual conversa do Chatwoot é de qual número. Esse vínculo diz para onde vai a resposta do agente e em qual conversa entra a próxima mensagem do cliente. Guarde numa tabela sua, não dependa de ler o telefone de dentro do evento.

Receber mensagens no Chatwoot

1. 1

   Cole a URL da ponte no Zapixo

   No painel do Zapixo, abra a instância e cole a URL da ponte em Webhook de mensagens. Cada mensagem do cliente chega como messages.upsert. Descarte fromMe: true, que é mensagem saindo da própria instância.

2. 2

   Encontre ou crie o contato

   Procure o contato pelo telefone no Chatwoot e crie se não existir. Normalize o número antes de comparar: o mesmo cliente não pode virar dois contatos por causa de um 9 a mais ou de um +55.

3. 3

   Poste a mensagem como recebida

   Na conversa vinculada ao número — ou numa nova, aberta na caixa do tipo API —, crie a mensagem com message_type igual a incoming. A autenticação é o header api_access_token, com o token de um agente ou bot do Chatwoot:

   POST https://seu-chatwoot.com/api/v1/accounts/{account_id}/conversations/{conversation_id}/messages
   api_access_token: SEU_TOKEN_DO_CHATWOOT
   Content-Type: application/json
   
   {
     "content": "Oi, quero saber o status do meu pedido",
     "message_type": "incoming"
   }

Erros comuns e como resolver

Mensagens em laço

A mensagem que a ponte cria no Chatwoot também dispara o webhook do Chatwoot, e a que o Zapixo envia pode voltar com fromMe: true. Os dois filtros juntos — outgoing do lado do Chatwoot e fromMe falso do lado do Zapixo — cortam o laço.

Nota privada chegou ao cliente

Faltou conferir private. Nota da equipe também gera message_created, e sem o filtro ela sai pelo WhatsApp.

Contato duplicado

O mesmo telefone escrito de dois jeitos vira dois contatos. Guarde e compare sempre só os dígitos, com DDI: 5511999999999.

Mensagem do cliente entra duas vezes

Se a ponte não devolver 2xx ao Zapixo em até 10 segundos, ele tenta de novo, até 3 vezes. Responda o webhook na hora e ignore data.key.id que já foi postado no Chatwoot.

Resposta do agente não sai

Confira a URL de webhook da caixa do tipo API, se a ponte responde ao Chatwoot, e se o número guardado no vínculo está só com dígitos. O 401 do Zapixo aponta chave errada; o 404, instance com nome diferente do painel.

Perguntas frequentes