CanaisWhatsApp
WhatsAppCanal · WhatsApp Cloud API · Meta oficial

Conectar WhatsApp Cloud API

Este é o canal mais importante para a maioria dos provedores. WhatsApp Cloud API é o canal oficial da Meta, regulado, seguro e que respeita as regras de janela de 24h e templates HSM.

Antes de começar: você precisa de um app criado no Meta for Developers (developers.facebook.com/apps) com produto WhatsApp Business ativado, e do número que você vai usar liberado para Cloud API (pode ser um número novo do M-Pesa-style ou portado).

Pré-requisitos

  • App em developers.facebook.com/apps com WhatsApp ativado
  • Phone Number ID do número que vai operar
  • WhatsApp Business Account ID (WABA ID)
  • System User com Access Token permanente com permissão whatsapp_business_messaging + whatsapp_business_management
  • App Secret (Settings → Basic)
  • Permissão canais:edit no ConectAI

Se você não sabe onde achar isso, consulte o tutorial passo-a-passo da Meta. Volte aqui quando estiver com os 5 valores.

Setup no ConectAI — passo a passo

  1. Acesse /config/canais — Configurações → Canais.

  2. Clique em + Adicionar canal → WhatsApp Cloud API.

  3. Preencha o formulário.

    CampoDescriçãoOnde achar
    Nome do canalNome interno (ex.: “Atendimento principal”)Você escolhe
    App IDID numérico do appApp → Settings → Basic → App ID
    Business Account IDWABA ID da contaAPI Setup → WhatsApp Business Account ID
    Phone Number IDID do númeroAPI Setup → From → Phone number ID
    Access TokenSystem User permanent tokenBusiness Manager → System Users → Generate token
    App SecretSegredo do appApp → Settings → Basic → App Secret (Show)
    Verify TokenString compartilhadaVocê cria, ou clique Gerar para UUID hex de 24 chars

    Os campos Access Token, App Secret e Verify Token têm botão de olho (show/hide) para evitar vazamento na sua tela.

  4. Clique em Testar e conectar.

    O ConectAI valida as credenciais via Graph API antes de salvar. Se algo estiver errado, o card volta com status: error e a mensagem da Meta aparece em vermelho.

  5. Configure o webhook na Meta.

    Após sucesso, o ConectAI exibe uma tela de “Últimos passos” com:

    • Callback URL (algo como https://app.conectaai.io/api/whatsapp/webhook/seu-canal-id)
    • Verify Token (o que você gerou)

    Vá em developers.facebook.com → seu app → WhatsApp → Configuration → Webhooks e:

    1. Cole a Callback URL
    2. Cole o Verify Token
    3. Clique em Verify and save
    4. Subscribe ao campo messages
    5. (Opcional) messaging_postbacks, message_reactions

  6. Mande uma mensagem de teste.

    Do seu celular, envie uma mensagem para o número configurado. Se tudo estiver certo, a IA responde em 1-3 segundos.

Editar credenciais depois

Em /config/canais, clique em Editar no card do canal. As credenciais sensíveis aparecem mascaradas (••••••••):

  • Se você não tocar no campo, o ConectAI mantém o valor anterior
  • Se você digitar algo novo, substitui

Útil pra renovar Access Token sem precisar redigitar todo o resto.

O que cada credencial faz

CredencialOnde é usada
Phone Number IDIdentifica o número na Meta para enviar mensagens
Access TokenAutentica todas as chamadas para a Graph API
App SecretValida assinatura X-Hub-Signature-256 dos webhooks (segurança)
Verify TokenHandshake inicial do webhook (a Meta usa pra confirmar que o URL é seu)
Business Account IDNecessário para listar/criar templates HSM

Boas práticas de Access Token

NUNCA use User Token nem Page Token. Eles expiram. Sempre System User permanent token (não expira até você revogar).

  • Nomeie o System User como conectai-bot para identificar de onde vem
  • Permissões mínimas: whatsapp_business_messaging, whatsapp_business_management, business_management
  • Regenere a cada 12 meses por higiene
  • Se vazar, revogue imediatamente em Business Manager → System Users

Troubleshooting

”Invalid OAuth access token”

Causa: token expirado, revogado ou copiado com espaços. Correção: gere um novo no Business Manager e cole limpo (sem aspas, sem espaços).

”(#100) The parameter phone_number_id is required”

Causa: Phone Number ID está em branco ou veio do lugar errado. Correção: Vá em WhatsApp → API Setup → From — o número da seleção tem o Phone Number ID logo abaixo.

”Webhook callback URL must use https”

Causa: você está testando local (http). Correção: o webhook precisa de URL HTTPS pública. Use o domínio de produção do ConectAI (ou ngrok pra testes).

”Hub.signature mismatch”

Causa: App Secret errado. Correção: copie de novo em App → Settings → Basic → App Secret → Show, atualize no ConectAI.

Mensagens de templates não chegam

Causa: template não aprovado ou variáveis incompletas. Correção: veja Templates HSM e a janela de 24h.

O canal cai em error depois de funcionar

Causa: geralmente Access Token revogado / expirado, ou número desabilitado na Meta. Correção: edite o canal, regere o token, reconecte.

Janela de 24h

A regra mais importante do WhatsApp:

Você só pode mandar mensagens livres por 24h após a última mensagem do cliente.

Passou disso, a Meta bloqueia tudo que não seja um template HSM aprovado.

SituaçãoPode mandar?
Cliente acabou de mandar uma mensagemQualquer coisa, por 24h
Cliente mandou ontem (>24h)Só templates HSM aprovados
Cliente NUNCA mandou nadaSó templates HSM aprovados
Você só quer responder o clienteQualquer coisa, dentro de 24h

→ Como criar templates HSM

Multi-número (múltiplos canais WhatsApp)

Você pode conectar vários números WhatsApp (cada um vira um canal separado):

  • Um canal para atendimento principal
  • Um canal para campanhas (cobrança/NPS)
  • Um canal regional (ex.: cidade A vs cidade B)

Cada canal tem suas próprias credenciais e seus próprios templates. Limites de canais variam por plano.

Próximo passo

→ Telefonia SIP
→ Templates HSM

Visão geralTelefonia