WhatsApp

O Hedhog suporta dois caminhos para WhatsApp:

• whatsapp-official — a WhatsApp Business Cloud API oficial da Meta. Recebe mensagens via webhook (assinado com HMAC) e gerencia os números do WABA. O envio ainda não está implementado.
• evolution-api — uma instância auto-hospedada da Evolution API, usada por uma ação de Integração de Webhook. Envia texto simples, mas é uma sessão não-oficial atrelada a um telefone.

Status: ⚠️ Parcial — whatsapp-official recebe mensagens (envio pendente); a Evolution API envia texto via ação de Integração de Webhook.

Procurando abrir chamado a partir de uma mensagem de WhatsApp e responder pelo mesmo número? Isso é o módulo SAC, e os dois providers funcionam lá: veja Atendimento omnichannel.

1. Em Settings → Integrations, crie um perfil do tipo whatsapp com o provider WhatsApp Official API e preencha com os dados do painel da Meta: Meta App ID, Meta App Secret, WABA ID, Business ID, access token (System User, permanente), verify token (escolhido por você) e a versão da Graph API (ex.: v21.0). Salve o perfil.
2. Reabra o perfil salvo: a seção Webhook da Meta mostra a Callback URL (com botão de copiar) e o passo a passo. Clique em Test para o Hedhog validar o token contra a Graph API.
3. Importe os números do WABA: POST /whatsapp/phone-numbers/sync/{integrationProfileId} — traz phone_number_id, quality rating e status de verificação direto da Meta.
4. Registre o webhook no painel da Meta com os dados abaixo.

Ambos aparecem na seção Webhook da Meta do perfil, prontos para copiar:

Depois de salvar, assine o campo messages no webhook do produto WhatsApp.

A URL usa o webhook do core: um UUID não-enumerável e rotacionável identifica o webhook, não o id do perfil. A Meta chama essa URL; o Hedhog delega ao adaptador do protocolo da Meta, que faz o handshake e valida o HMAC. O webhook também aparece em Settings → Integrations and Webhooks, com logs.

• Todo POST é validado com HMAC SHA-256 (X-Hub-Signature-256) sobre o corpo bruto, usando o Meta App Secret. Assinatura inválida → 403, sem enfileirar.
• App Secret, access token e verify token são cifrados em repouso e nunca devolvidos pela API (a UI mostra ********).
• A validação da assinatura só pode ser desligada em desenvolvimento (WHATSAPP_WEBHOOK_SKIP_SIGNATURE=true); em produção a flag é ignorada.

Um WABA pode ter vários números, e cada um tem estado próprio. O Hedhog guarda cada número separadamente, permite marcar um padrão por perfil (garantido no banco) e ativar/desativar individualmente. O número destinatário de cada webhook é identificado automaticamente pelo metadata.phone_number_id.

1. Auto-hospede a Evolution API e crie uma instância de WhatsApp (comandos abaixo)
2. Vá em Settings → Integrations and Webhooks, abra (ou crie) uma Webhook Integration e adicione uma ação WhatsApp (Evolution API)
3. Preencha os campos whatsapp_* diretamente na ação — nenhum Perfil de Integração necessário
4. Envie uma mensagem de teste e confirme que ela é de fato entregue ao telefone vinculado, não apenas um HTTP 200

docker run -d \
  --name evolution-api \
  -p 8080:8080 \
  -e AUTHENTICATION_API_KEY=your-api-key \
  atendai/evolution-api:latest

Substitua your-api-key por uma string aleatória segura — isso se torna o cabeçalho apikey que o Hedhog envia em cada requisição. O dashboard de gerenciamento fica disponível em http://localhost:8080.

Crie uma sessão de WhatsApp ("instância") antes de enviar qualquer coisa:

curl -X POST http://localhost:8080/instance/create \
  -H "apikey: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"instanceName": "my-instance", "qrcode": true}'

Escaneie o QR code retornado a partir de um telefone em WhatsApp → Aparelhos conectados → Conectar um aparelho. A sessão permanece ativa enquanto aquele telefone tiver acesso à internet — perder a conexão do telefone derruba a sessão e as mensagens começarão a falhar até você reconectar.

1. Vá em Settings → Integrations and Webhooks, abra (ou crie) uma Webhook Integration
2. Adicione uma ação do tipo WhatsApp (Evolution API) e preencha, diretamente na ação:

Esta ação só envia texto simples via sendText — ela não suporta mídia, botões ou listas.

• A WhatsApp Business Policy restringe mensagens em massa/não solicitadas a contatos que deram opt-in — enviar para pessoas que nunca consentiram arrisca ter o número banido pelo WhatsApp, não apenas pela Evolution API
• Sessões da Evolution API atreladas a um número de telefone pessoal são inerentemente frágeis: uma bateria descarregada, um logout do app ou a perda de conectividade naquele telefone quebra toda integração que depende dele
• O whatsapp-official recebe mensagens, mas ainda não envia — para enviar hoje, use a ação da Evolution API
• O download de mídia recebida (imagens, áudios) ainda não é feito: o Hedhog guarda a referência (id, mime_type) devolvida pela Meta, não o binário

API oficial: no painel da Meta, o botão Verify and save do webhook deve passar (o Hedhog devolve o hub.challenge). Depois, envie uma mensagem real para o número de produção e confirme que ela aparece nas tabelas whatsapp_conversation/whatsapp_message — não basta o 200 do webhook, porque o processamento acontece na fila.

Evolution API: dispare a ação de webhook uma vez e confirme que a mensagem de fato chega ao telefone vinculado — não apenas que a chamada HTTP retornou 200. Verifique no dashboard da Evolution API se a instância ainda aparece como conectada.