Conectar WhatsApp oficial (Datafy)
Este é o caminho da API oficial do WhatsApp (Meta), intermediada pela Datafy. Ele exige um número aprovado e um app configurado na Meta. Se você quer ligar um número comum lendo um QR code, use o caminho não oficial (uazapi).
São três etapas, nesta ordem:
- Preencher o trio de credenciais no card do agent.
- Criar o canal de entrada e copiar a URL.
- Colar a URL no painel da Datafy e assinar os eventos.
1. O trio de credenciais
No agent, vá em Integrations → card WhatsApp oficial (“Integre este agent ao WhatsApp oficial usando a API Datafy”).
São três campos:
| Campo | O que é |
|---|---|
| Token Datafy | O token de acesso usado para enviar mensagens. |
| Token de verificação do webhook | Uma senha que você inventa. A Meta a devolve na hora de validar o webhook, e a plataforma confere se bate. |
| App Secret | O App Secret do app Meta/Datafy. É com ele que a plataforma valida a assinatura de cada webhook recebido. |
Os três andam sempre juntos. Salvar só um ou dois é recusado pela plataforma, e limpar significa apagar os três de uma vez. Se você só quer trocar um deles, preencha os três de novo.
Depois de salvar, a etiqueta do card muda para Configurado. Os valores nunca mais
são exibidos: ao reabrir a tela os campos aparecem como •••••••• (manter atual).
Deixá-los assim mantém o que já está gravado.
2. Criar o canal de entrada
O canal de entrada é o vínculo que diz “mensagens que chegarem por aqui são deste agent”. Sem ele, as mensagens não têm para onde ir.
Abra a seção Inbound channels
No menu lateral do agent, clique em Inbound channels.
Escolha o provedor
No campo Provider, escolha datafy.
(Opcional) Defina um secret
Se preencher o secret, a plataforma passa a exigir assinatura em cada entrega
(verificação hmac_sha256). Sem secret, a verificação fica como none e a única
proteção é o endereço secreto da URL. Recomendado: preencher.
Copie a URL
Ao criar, a plataforma mostra a URL pública do canal, algo no formato:
https://SEU_GATEWAY/inbound-webhook/00000000-0000-0000-0000-000000000000Essa URL aparece uma única vez. Copie no ato e guarde num lugar seguro. Ela é uma credencial: quem a tiver consegue enviar mensagens para dentro deste agent. Se perder, apague o canal e crie outro.
3. Configurar no painel Datafy
Cole a URL do webhook
Cole a URL copiada no campo de webhook (callback URL) do painel Datafy.
Informe o token de verificação
Use exatamente o mesmo Token de verificação do webhook que você gravou no card do agent. A validação inicial da Meta só passa se os dois forem idênticos.
Assine os eventos
Marque as duas:
messages— obrigatória. É ela que entrega a mensagem enviada pelo cliente. Sem essa assinatura o agent nunca é acionado.smb_message_echoes— obrigatória para capturar o atendente humano. Entrega uma cópia das mensagens enviadas pelo próprio número quando um humano digita no aplicativo do WhatsApp Business.
O que a plataforma faz com cada uma: de messages ela lê as mensagens recebidas do
cliente e aciona o agent. De smb_message_echoes ela reconhece a fala do atendente
humano — grava no histórico da conversa com o papel de operador, marca a conversa
como human_handled e espelha para os seus webhooks como conversation.operator. A
API não ecoa mensagens por esse campo, então não existe risco do robô responder a si
mesmo. O comportamento é o mesmo do canal não oficial (uazapi) — veja
Atendimento humano.
Como saber se funcionou
- Mande uma mensagem de WhatsApp para o número do cliente, de outro telefone.
- Espere alguns segundos: a plataforma agrupa mensagens antes de responder.
- O agent deve responder.
Se nada acontecer, siga o checklist de Quando algo dá errado.
A janela de 24 horas da Meta
No WhatsApp oficial existe uma regra da própria Meta que não é nossa e não tem como contornar: depois que o cliente manda uma mensagem, você tem 24 horas para responder o que quiser, com texto livre. Passadas as 24 horas — ou se o cliente nunca escreveu —, a Meta só aceita um modelo aprovado por ela.
A plataforma respeita isso sozinha:
| Situação | O que acontece |
|---|---|
| O cliente falou nas últimas 24 horas | O agent responde normalmente, com texto livre. Nenhum limite |
| Passou de 24 horas e você tem um modelo cadastrado | A plataforma manda o modelo, a janela reabre, e a conversa segue |
| Passou de 24 horas e você não tem modelo cadastrado | A mensagem é descartada e você recebe um aviso no seu canal de avisos — uma vez por conversa por dia, para não virar spam de aviso |
O modelo serve para bater na porta: ele reabre a janela. O texto que o agent tinha escrito naquele momento não é enviado junto — a Meta não permite texto livre ali. Assim que o cliente responder ao modelo, a janela reabre e a conversa continua normal.
Cadastrar o modelo aprovado
- Crie e envie o modelo para aprovação no painel da Meta/Datafy, como qualquer template.
- Anote o nome exato do modelo e o código do idioma (por exemplo
pt_BR). - Peça para a gente gravar os dois na política de envio do agent.
Sem esse cadastro, todo disparo iniciado fora da janela é perdido — o aviso que você recebe é justamente para lembrar de fazê-lo.
Os limites de disparo valem aqui também
Os tetos de envio iniciado (por dia, por hora), o espaçamento entre mensagens e a pausa automática por falhas funcionam igual ao canal não oficial. A tabela completa está em Protegendo o número — vale para os dois canais.
Problemas comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Erro ao salvar o card WhatsApp oficial | Você preencheu só um ou dois dos três campos | Preencha os três juntos e salve de novo |
| A Meta recusa o webhook na validação | Token de verificação diferente do gravado no agent | Confira caractere por caractere; ele é inventado por você e precisa ser idêntico nos dois lados |
| Webhook validado, mas o agent não recebe nada | Falta a assinatura messages, ou a URL colada não é a do canal deste agent | Confira a assinatura no painel Datafy e recrie o canal de entrada se tiver perdido a URL |
| Mensagens chegam, mas nenhuma resposta sai | Credenciais do Claude ausentes | Veja o aviso vermelho na página do agent — Criar e configurar um agent |
| “Você não tem permissão de administrador para esta ação” ao criar o canal | Sua conta não tem acesso àquela organização | Peça a um administrador para criar o canal |