> ## Documentation Index
> Fetch the complete documentation index at: https://chatcli.edilsonfreitas.com/llms.txt
> Use this file to discover all available pages before exploring further.
# WhatsApp
> Converse com o ChatCLI no WhatsApp pela WhatsApp Business Cloud API: um webhook verificado e assinado que o gateway serve, com mensagens de voz e imagem recebidas e respostas com imagem.
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.
| | WhatsApp |
| - | - |
| Transporte | Webhook da Cloud API servido pelo gateway; respostas pela Graph API |
| Quem pode falar com o bot | Qualquer pessoa que mande mensagem para o número; não há lista de permitidos |
| Voice notes recebidas | Sim |
| Respostas em voz | Não (só texto) |
| Imagens recebidas | Sim (a legenda não é lida) |
| Imagens enviadas | Sim |
| Sinal de "trabalhando" | Um aviso curto em texto se a resposta passar de uns 2 segundos |
## Configuração
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.
```bash theme={"system"}
export CHATCLI_WHATSAPP_ACCESS_TOKEN="..."
export CHATCLI_WHATSAPP_PHONE_ID="123456789012345"
export CHATCLI_WHATSAPP_APP_SECRET="..." # verifica cada entrega
export CHATCLI_WHATSAPP_VERIFY_TOKEN="meu-verify" # o texto que você escolheu
export CHATCLI_WHATSAPP_ADDR=":8082"
# export CHATCLI_WHATSAPP_PATH="/whatsapp/webhook" # o padrão
```
```text theme={"system"}
/gateway start
/gateway status # whatsapp deve aparecer
```
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
| Variável | Obrigatória | Padrão | O que faz |
| - | - | - | - |
| `CHATCLI_WHATSAPP_ACCESS_TOKEN` | sim | — | Token da Graph API usado para baixar mídia e enviar respostas. |
| `CHATCLI_WHATSAPP_PHONE_ID` | sim | — | Phone number ID de onde as respostas saem. |
| `CHATCLI_WHATSAPP_ADDR` | sim | — | Endereço do servidor do webhook, por exemplo `:8082`. O adaptador só liga com o token, o phone ID e o endereço definidos. |
| `CHATCLI_WHATSAPP_APP_SECRET` | sim, na prática | — | Verifica o `X-Hub-Signature-256` de cada entrega. Sem ele toda mensagem recebida é recusada com `401`, e um aviso é registrado no start. |
| `CHATCLI_WHATSAPP_VERIFY_TOKEN` | sim, na prática | — | Responde à verificação do webhook pela Meta. Sem ele a verificação é recusada com `403`, e um aviso é registrado no start. |
| `CHATCLI_WHATSAPP_PATH` | não | `/whatsapp/webhook` | Caminho do webhook. |
| `CHATCLI_WHATSAPP_HOME_CHANNEL` | não | — | Número padrão das [mensagens proativas](/pt/gateway/proactive-messaging) enviadas com `@send whatsapp`. |
## 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](/pt/security/overview) 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](/pt/gateway/proactive-messaging) 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
Como as mensagens rodam, voz, imagens, continuidade e os outros canais.
Mande a primeira mensagem com `@send`, dentro da janela de 24 horas do WhatsApp.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.