Skip to main content
O adaptador do WhatsApp usa a WhatsApp Business Cloud API da Meta. A Meta entrega as mensagens num webhook que o gateway serve, então o endpoint precisa estar acessível por HTTPS pela internet, e toda entrega é conferida contra o app secret.

​
Configuração

1

Prepare o app da Meta

No Meta for Developers, crie um app com o produto WhatsApp. Anote o access token, o phone number ID do número que vai responder e o App Secret do app (App settings → Basic). Escolha um verify token seu: qualquer texto que você vai digitar nos dois lugares.
2

Configure o ChatCLI

3

Inicie o gateway

4

Registre o webhook

Na configuração do WhatsApp no app, defina a callback URL como o endereço HTTPS público que chega em CHATCLI_WHATSAPP_ADDR e CHATCLI_WHATSAPP_PATH, por exemplo https://bot.example.com/whatsapp/webhook, e o verify token como o mesmo texto. A Meta confere na hora, então o gateway já precisa estar rodando. Depois inscreva o webhook no campo messages.

​
Variáveis de ambiente

​
Quem alcança o bot

Entregas sem assinatura válida são recusadas, então só a Meta alimenta o webhook. Passada essa barreira, qualquer pessoa que mande mensagem para o número chega ao agente, que roda com suas tools e o shell.
O WhatsApp não tem lista de remetentes permitidos. Use um número que só as pessoas certas conhecem e endureça o agente com o modo de segurança antes de expor.

​
Mensagens

  • Tipos atendidos: texto, áudio (voice notes) e imagens. Vídeo, documentos, figurinhas, localização, reações e mensagens interativas são ignorados.
  • Voz: o áudio é baixado pela Graph API e transcrito antes de o agente rodar.
  • Imagens: a imagem chega ao modelo com uma instrução padrão para descrevê-la; a legenda digitada junto com a imagem não é lida, então mande a pergunta numa mensagem separada.
  • Respostas com imagem são enviadas ao WhatsApp e mandadas com o texto da resposta como legenda; se falhar, o texto vai sozinho.
  • Cada remetente é uma conversa, identificada pelo número de telefone.

​
Limites

  • Uma resposta é cortada em 3500 caracteres e termina com ….
  • O WhatsApp só aceita mensagens livres até 24 horas depois da última mensagem da pessoa. Uma mensagem proativa fora dessa janela falha, porque o gateway não envia templates.
  • A Meta reenvia uma entrega cujo recebimento não viu confirmado a tempo; uma entrega reenviada é processada de novo.

​
Solução de problemas

O gateway precisa estar rodando e alcançável na URL, e CHATCLI_WHATSAPP_VERIFY_TOKEN precisa ser igual ao token digitado no painel da Meta. Com a variável vazia, a verificação é recusada com 403.
Defina CHATCLI_WHATSAPP_APP_SECRET: sem ele toda entrega é recusada com 401. ~/.chatcli/gateway.log mostra uma linha “rejected an inbound delivery with no valid signature” para cada uma. Confira também se o webhook está inscrito no campo messages.

​
Veja também

Chat gateway

Como as mensagens rodam, voz, imagens, continuidade e os outros canais.

Mensagens proativas

Mande a primeira mensagem com @send, dentro da janela de 24 horas do WhatsApp.