O que é
API Cloud oficial da Meta — sem risco de ban, mas quem decide o que pode ser enviado é a Meta. Envio proativo exige template aprovado.
Este canal está em beta: funciona, mas ainda não foi exercitado em produção por muitos clientes. Conte o que encontrar.
Configurar
Cerca de 20 minutos até um canal funcionando.
- 01Crie um app Business na Meta. developers.facebook.com → My Apps → Create App → tipo Business. É preciso ter uma conta Meta Business; criar uma leva poucos minutos.
- 02Adicione o produto WhatsApp e abra API Setup. Essa tela mostra o Phone number ID (copie) e um access token temporário que vale 24 h — serve para o primeiro teste, não para produção.
- 03Cadastre o seu número em “To”. Enquanto o app está em teste, a Meta só entrega para números verificados nessa lista. Pular este passo é a causa mais comum de “diz que enviou e não chegou nada”.
- 04Gere um token permanente. Business Settings → Users → System Users → criar → Add Assets (o app do WhatsApp) → Generate new token com a permissão whatsapp_business_messaging. Esse não expira.
- 05Crie um template e espere a aprovação. WhatsApp Manager → Message templates. O corpo pode declarar quantos parâmetros você quiser, inclusive nenhum — o campo Parâmetros do template abaixo diz o que entra em cada um. Para anexar o arquivo do relatório, o template também precisa declarar um header do tipo DOCUMENT. A aprovação leva de minutos a horas.
- 06Preencha os campos aqui e clique em Testar. O Testar valida o token e o phone number id contra a Graph API sem enviar mensagem. O envio de verdade acontece quando o relatório roda.
Campos
| Campo | Obrigatório | O que é |
|---|---|---|
| Phone Number ID | Sim | App da Meta → WhatsApp → API Setup. É um id numérico, não o telefone em si. (1234567890) |
| Access token | Sim | Token temporário do API Setup (24 h) para o primeiro teste, ou token permanente de System User para produção. |
| Versão da API | Não | Versão da Graph API. Deixe v21.0 enquanto a Meta não descontinuar. (v21.0) |
| Template aprovado | Não | Obrigatório para envio proativo. Quantos parâmetros o corpo declara é com você — o campo abaixo diz o que preenche cada um. Header DOCUMENT é necessário quando o relatório gera arquivo (CSV/XLSX/PDF), e dispensável quando é Inline HTML. Vazio significa texto livre, que a Meta só entrega dentro da janela de 24 h. (report_ready) |
| Idioma do template | Não | Código de idioma da Meta do template aprovado, ex.: pt_BR ou en_US. Divergência aqui volta como “template not found”, que aponta para o nome e não para o idioma. Em branco, cai para en_US. (pt_BR) |
| Parâmetros do template | Não | Uma linha por parâmetro do corpo do template aprovado: a linha 1 preenche {{1}}, a linha 2 preenche {{2}}, e assim por diante. Use {{message}} para o texto do relatório, e qualquer placeholder do relatório — {{report_name}}, {{rows}}, {{result_summary}}, {{date}}. A Meta recusa o envio quando a quantidade difere da que o template declara (erro 132000). Em branco, manda um parâmetro só com a mensagem inteira, que é o certo para um template escrito como um {{1}} sozinho; um - sozinho significa que o template não recebe parâmetro nenhum, que é o certo para um de texto fixo. ({{message}}) |
O que vai em Target
O telefone de quem recebe, formato internacional e só dígitos: 5511999999999. Sem +, espaços ou traços — o resto é descartado antes da chamada.
Target é obrigatório neste canal: uma rota sem Target não sai. — 5511999999999
Testar
Cada canal tem o botão Testar na lista de canais (Configurações → Canais). O resultado fica guardado — data, status e o erro do provedor quando houve — e um canal nunca testado aparece marcado na lista.
Testar valida o access token e o phone number id contra a Meta, sem enviar mensagem. A primeira entrega real é o que prova o template e a janela de 24 horas.
Conferir de ponta a ponta
- 01Relatório: abra um relatório, adicione este canal em Destinos (com o Target, se o canal pede), clique em Executar agora e abra a execução. O log diz por qual canal cada destinatário foi e o que o provedor respondeu.
- 02Alerta: em Monitoramento → Rotas de alerta, crie uma rota com este canal como passo de escalação. A rota casa por severidade e origem; a primeira que casar vence.
- 03Para disparar um alerta sem derrubar nada: crie um monitor HTTP apontando para uma URL que responde erro (por exemplo https://httpstat.us/500) com intervalo curto. Quando ele cair, o alerta sai pela rota; apague o monitor depois. A mensagem traz um link de reconhecimento — clique nele e a escalação para.
- 04Regras de relatório (linhas novas, valor fora da faixa) chegam pela mesma rota, com origem "regra de relatório".
O que mais costuma dar errado
Fora da janela de 24 h a Meta só entrega template aprovado. Com o campo Template aprovado vazio, um relatório sai como texto livre — ou seja, não chega em quase ninguém e não acusa erro; uma campanha se recusa a enviar em vez de fingir. É regra da Meta, não bug do DataRunner.