Guia de conexão

Conectar o WhatsApp oficial

Você cria um app na Meta, copia quatro dados para o console e cola na Meta a URL de webhook que o console devolve. Daí em diante, cada mensagem do número chega ao agente.

Antes de começar, crie o agente em Agentes, no console. O número conectado aqui passa a ser atendido por ele.

1. Crie o app na Meta

Abra developers.facebook.com/apps e clique em Create App.
Dê um nome ao app e informe o seu e-mail.
Escolha o caso de uso Connect with customers through WhatsApp e clique em Next.
Escolha o portfólio empresarial da sua empresa (ou crie um), revise os requisitos e clique em Create app.

2. Pegue o phone number id e o WABA id

Na tela Quickstart, clique em Start using the API para abrir API Setup. Conecte a conta do WhatsApp Business (a Meta chama de Messaging account) ou crie uma. Em From, escolha o número ou adicione o número da empresa.

Na Meta	Campo no Mensageiro
Phone number ID	`phone_number_id`
Messaging account ID (WhatsApp Business Account ID)	`waba_id`

3. Gere um token permanente

O token do botão Generate access token expira em pouco tempo. O agente precisa de um token de System User, que não expira:

Em Business Settings, abra System users e clique em Add para criar o usuário.
Selecione o usuário e clique em Assign Assets. No app, ative Manage app (Full control). Na conta do WhatsApp, ative Manage WhatsApp Business accounts (Full control). Confirme em Assign assets.
Clique em Generate token com as permissões business_management, whatsapp_business_messaging e whatsapp_business_management.

Esse token vai no campo access_token. A permissão whatsapp_business_messaging é a que libera o webhook de mensagens.

4. Copie o app secret

Em App settings → Basic, copie o App secret. Ele vai no campo app_secret. A Meta assina cada webhook com ele no cabeçalho X-Hub-Signature-256, e o Mensageiro recusa toda mensagem cuja assinatura não confere.

5. Conecte o canal no Mensageiro

No console, abra o agente e conecte um canal do tipo WhatsApp oficial com os quatro campos: phone_number_id, waba_id, access_token e app_secret. Pela API, é a mesma chamada:

bash

1curl https://api.mensageiro.ai/v1/agents/ID_DO_AGENTE/channels \

2 -H "Authorization: Bearer sk-msg-SUA_CHAVE" \

3 -H "Content-Type: application/json" \

4 -d '{

5 "kind": "wa_cloud",

6 "phone_number_id": "SEU_PHONE_NUMBER_ID",

7 "waba_id": "SEU_WABA_ID",

8 "access_token": "TOKEN_DO_SYSTEM_USER",

9 "app_secret": "APP_SECRET_DO_APP"

10 }'

A resposta traz o webhook_url e o verify_token do canal. O token e o app secret ficam selados e nunca voltam numa resposta.

json

1{

2 "data": {

3 "id": "ch_…",

4 "kind": "wa_cloud",

5 "status": "active",

6 "label": "SEU_PHONE_NUMBER_ID",

7 "webhook_url": "https://api.mensageiro.ai/api/channels/wa/ch_…",

8 "verify_token": "…",

9 "webhook_set": null,

10 "last_error": null

11 }

12}

6. Configure o webhook na Meta

Abra WhatsApp → Configuration no painel do app. Em apps criados pelo caso de uso, o caminho é Use cases → Customize → Configuration.
Em Callback URL, cole o webhook_url. Em Verify token, cole o verify_token. A Meta faz uma chamada de verificação; o Mensageiro responde e o painel salva.
Em Webhook fields, assine o campo messages. É ele que entrega as mensagens dos clientes.

7. Inscreva o app na conta e coloque em modo Live

A Meta entrega webhooks só das contas em que o app está inscrito. Se o app ainda não aparece inscrito na conta do WhatsApp Business, faça a inscrição com o mesmo token:

bash

1curl -X POST "https://graph.facebook.com/v26.0/SEU_WABA_ID/subscribed_apps" \

2 -H "Authorization: Bearer TOKEN_DO_SYSTEM_USER"

A resposta é {"success": true}. Por último, mude o app para o modo Live: em modo de desenvolvimento, a Meta não envia parte dos webhooks.

8. Teste

Mande uma mensagem de outro celular para o número. O agente responde e a conversa aparece no console, com o contato e as mensagens. Escreva atendente e o agente pausa por 12 horas para aquele contato.

Se algo não funcionar

Sinal	O que conferir
A Meta não salva o webhook	O Verify token precisa ser o `verify_token` do canal, sem espaços.
Nenhuma mensagem chega	O campo `messages` assinado, o app inscrito na conta (passo 7) e o app em modo Live.
O canal fica com `status` `error`	Leia `last_error` no canal e confira se o token é de System User e tem as três permissões do passo 3.
Áudio ou imagem sem resposta	O agente responde texto e pede ao cliente para escrever. Grupos e status ficam de fora.

Para usar uma instância da Evolution API no lugar da API oficial, veja Conectar Evolution API. Os preços por mensagem estão em preços.