Documentação da API
Para quem vai integrar o sistema da empresa ao WhatsApp oficial. Endereço: https://canalapioficial.solucoesdeia.com. Tudo em JSON, UTF-8, horários em ISO 8601 (UTC).
1. Visão geral e conceitos
- Empresa
- O seu cadastro conosco. Tudo (números, templates, mensagens, webhooks) pertence a uma empresa e nenhuma empresa enxerga dados de outra.
- Número
- O WhatsApp da empresa ligado à API oficial da Meta, dentro da conta WhatsApp Business (WABA) de vocês. Pode haver mais de um; aí envie
fromcom ophone_number_id. - Template
- Modelo de mensagem aprovado pela Meta. É obrigatório para começar uma conversa. Tem variáveis (
{{nome}}), cabeçalho opcional (texto, imagem, vídeo ou documento) e botões. - Janela de 24 h
- Quando o contato escreve, abre-se uma janela de 24 horas em que vocês podem mandar texto livre, mídia e botões sem template. Fora dela, só template.
- Categorias
- Utilidade (confirmação, cobrança, aviso), marketing (oferta, campanha) e autenticação (código). A categoria define o preço da Meta e as regras de entrega; marketing tem limites mais duros.
- Quem paga a Meta
- Vocês, direto no meio de pagamento da conta WhatsApp no Gerenciador de Negócios. A Soluções de IA cobra a assinatura da plataforma, a conexão e o suporte, nunca por mensagem. O custo que mostramos é só informativo.
- Ambiente de teste
- Credencial em modo sandbox: mesma API, nada vai para a Meta, e os status (enviada, entregue, lida, falha) são simulados. Telefone terminado em 0002 simula falha 131026.
2. Autenticação
- Nós criamos uma credencial para vocês:
client_id(público) eclient_secret(mostrado uma vez). Guardem o segredo no cofre do servidor, nunca no navegador ou no aplicativo. - Troquem a credencial por um token de acesso de 1 hora em
POST /oauth/token(OAuth2 client_credentials). - Mandem o token em toda chamada:
Authorization: Bearer <access_token>. Reaproveitem até perto de vencer; recebeu 401, peçam outro.
curl -s -X POST https://canalapioficial.solucoesdeia.com/oauth/token \
-d grant_type=client_credentials \
-d client_id=$CANAL_CLIENT_ID \
-d client_secret=$CANAL_CLIENT_SECRET
# {"access_token":"cat_live_...","token_type":"Bearer","expires_in":3600,"scope":"messages:send messages:read ..."}Escopos
| Escopo | Libera |
|---|---|
messages:send | Enviar mensagens, eventos, mídia e registrar opt-out |
messages:read | Consultar mensagens, conversas, números e baixar mídia recebida |
templates:read | Listar templates, schema, prévia e eventos configurados |
templates:write | Criar templates e configurar disparo por evento |
webhooks:manage | Cadastrar webhooks e reenviar entregas |
numbers:manage | Conectar números pelo cadastro incorporado |
Para pedir menos escopos num token, mande scope=messages:read no /oauth/token. Cada credencial pode ter limite próprio, lista de IPs e data de validade; revogar ou trocar o segredo corta os tokens na hora.
3. Guias
Enviar template (variáveis, PDF no cabeçalho, botões)
Variáveis vão por nome. Dinheiro em centavos (35000 = R$ 350,00) e datas em AAAA-MM-DD: nós formatamos como o template pede. Documento no cabeçalho por url + filename ou por media_id. Botões: copy_code (copiar código, Pix) e url_suffix (final do link). Endpoint: POST /v1/messages. Eventos: message.queued → message.sent → message.delivered → message.read ou message.failed.
curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/messages \
-H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{ "to": "5531999990000", "client_message_id": "fatura-2026-10-8841", "template": { "name": "boleto_mensal", "language": "pt_BR", "variables": { "nome": "Ana", "valor": 35000, "vencimento": "2026-10-30" }, "header": { "document": { "url": "https://erp.cliente.com.br/boletos/8841.pdf", "filename": "Fatura outubro.pdf" } }, "buttons": { "copy_code": "23793381286000000000300000000400198760000035000", "url_suffix": "8841" } }, "metadata": { "ref": "8841" } }'Texto livre dentro da janela de 24 h
Depois que o contato escreve, mandem texto, mídia ou botões sem template. Fora da janela a API responde outside_window. Botões: até 3 (título até 20 letras). Lista: até 10 opções. GET /v1/conversations mostra window_open_until de cada contato.
{ "to": "5531988880000", "type": "text", "text": { "body": "Temos vaga para 20/12. Posso reservar?" } }
{ "to": "5531988880000", "type": "interactive",
"interactive": { "type": "button", "body": "Confirma a reserva?",
"buttons": [ { "id": "sim", "title": "Confirmar" }, { "id": "nao", "title": "Mudar data" } ] } }Validar antes com dry_run
POST /v1/messages?dry_run=true faz todas as validações sem gravar nem enviar. Devolve a categoria, o custo informativo da Meta, se a janela está aberta e quanto o número ainda pode iniciar hoje. Se houver erro, vem 422 com todos os problemas em errors[].
{ "dry_run": true, "valid": true, "conversation_category": "utility",
"estimated_cost_cents": 28, "window_open": false,
"number": { "tier": 1000, "remaining_today": 873, "quality_rating": "green" }, "warnings": [] }
{ "error": { "code": "template_variables_mismatch", "param": "template.variables.valor",
"message": "\"valor\" é currency: envie inteiro em centavos (ex.: 35000 = R$ 350,00).",
"errors": [ { "code": "template_variables_mismatch", "param": "template.variables.valor", "message": "..." },
{ "code": "media_invalid", "param": "template.header", "message": "..." } ] } }Idempotência (client_message_id)
Mandem sempre o id do seu sistema em client_message_id (ou no cabeçalho Idempotency-Key). Se a rede cair e vocês repetirem, voltamos a mesma resposta com idempotent_replayed: true e nada é enviado de novo. Mesma chave com outro conteúdo: idempotency_conflict. A chave vale 24 h; depois disso o índice único da mensagem ainda impede envio duplicado.
Consultar status
GET /v1/messages/{id} (nosso id ou o wamid) traz o status e a linha do tempo. GET /v1/messages?client_message_id=... acha pela sua chave. Status: queued, sent, delivered, read, failed, received e unknown (a Meta não respondeu a tempo; não reenvie, o status chega depois). O status nunca volta para trás.
Criar template e acompanhar a aprovação
POST /v1/templates com os components no formato da Meta (ou library_template_name para usar a biblioteca pronta). Informem os tipos das variáveis em variables (ou depois em PUT /v1/templates/{id}/schema). A aprovação chega pelo webhook template.status; POST /v1/templates/{id}/preview mostra o texto final.
{
"name": "boleto_mensal", "language": "pt_BR", "category": "UTILITY", "parameter_format": "NAMED",
"components": [
{ "type": "HEADER", "format": "DOCUMENT" },
{ "type": "BODY", "text": "Olá {{nome}}, sua fatura de {{valor}} vence em {{vencimento}}.",
"example": { "body_text_named_params": [
{ "param_name": "nome", "example": "Ana" }, { "param_name": "valor", "example": "R$ 350,00" },
{ "param_name": "vencimento", "example": "30/10/2026" } ] } },
{ "type": "BUTTONS", "buttons": [ { "type": "COPY_CODE", "example": "23793381286..." },
{ "type": "URL", "text": "Ver fatura", "url": "https://erp.cliente.com.br/f/{{1}}", "example": ["8841"] } ] }
],
"variables": { "valor": { "type": "currency", "format": "BRL" }, "vencimento": { "type": "date", "format": "dd/MM/yyyy" } }
}Mídia e PDF
Dois jeitos: (1) url pública https direto no envio, a Meta baixa; (2) POST /v1/media com url ou base64 (até ~4 MB por requisição) e usem o media_id devolvido por 30 dias. O mesmo arquivo pelo mesmo número reaproveita o media_id. Mídia recebida: GET /v1/media/{media_id}.
Disparo por evento
Configurem uma vez POST /v1/event-triggers (evento → template). Depois o sistema só avisa o que aconteceu em POST /v1/events com as variáveis; montamos e enviamos o template. Útil para reserva confirmada, check-out, fatura gerada.
curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/event-triggers -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"event":"reserva_confirmada","template":"confirmacao_reserva","language":"pt_BR"}'
curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/events -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"event":"reserva_confirmada","to":"5561999990000","client_message_id":"reserva-4471",
"variables":{"nome":"Carla","checkin":"2026-12-20","valor":128000},"buttons":{"url_suffix":"4471"}}'4. Webhooks
Cadastrem a URL https do sistema em POST /v1/webhooks (o segredo aparece só na resposta). Cada evento chega num POST:
POST https://sistema.cliente.com.br/webhooks/whatsapp
X-Canal-Event: message.delivered
X-Canal-Delivery: 6c1f0b9e-... (id da entrega: use para não processar duas vezes)
X-Canal-Timestamp: 1763452800
X-Canal-Signature: v1=5d41402abc4b2a76b9719d911017c592...
{ "id": "6c1f0b9e-...", "type": "message.delivered", "created_at": "2026-11-18T10:00:00Z", "tenant": "hotel-pires",
"data": { "message": { "id": "0d7e...", "status": "delivered", "to": "5531999990000",
"client_message_id": "fatura-2026-10-8841", "metadata": { "ref": "8841" } },
"status_at": "2026-11-18T10:00:00Z" } }| Evento | Quando |
|---|---|
message.queued | Aceitamos a mensagem |
message.sent / message.delivered / message.read | A Meta enviou / chegou no aparelho / o contato leu |
message.failed | Falhou; data.meta_error traz o código da Meta |
message.received | O contato mandou mensagem (texto, mídia, localização...) |
button.clicked | Clique em botão de template ou de mensagem interativa (payload e mensagem de origem) |
contact.opted_out | O contato pediu para sair (SAIR, PARAR, STOP) ou vocês registraram |
template.status | Template aprovado, rejeitado, pausado |
number.quality | Mudança de limite/qualidade do número |
Verificar a assinatura
HMAC-SHA256 de timestamp + "." + corpo cru com o segredo do webhook. Recusem assinatura errada e horário com mais de 5 minutos de diferença.
import { createHmac, timingSafeEqual } from "node:crypto";
// use o corpo CRU (string/bytes), antes de qualquer JSON.parse
export function assinaturaValida(corpoCru, headers, segredo) {
const ts = headers["x-canal-timestamp"];
const veio = headers["x-canal-signature"] || "";
const esperado = "v1=" + createHmac("sha256", segredo).update(ts + "." + corpoCru).digest("hex");
const recente = Math.abs(Date.now() / 1000 - Number(ts)) < 300;
return recente && veio.length === esperado.length && timingSafeEqual(Buffer.from(veio), Buffer.from(esperado));
}Recebimento de resposta e clique em botão
Mensagens e cliques chegam pelo webhook único da Meta, que conferimos (assinatura da Meta), gravamos antes de responder e encaminhamos pelo número que recebeu. SAIR vira opt-out automático.
Status da mensagem (sent, delivered, read, failed)
A Meta avisa cada mudança. Ligamos ao envio original (inclusive quando o status chega antes da resposta do envio) e repassamos com o mesmo id, client_message_id e metadata.
Reenvio de webhook
Respondam 2xx em até 8 s. Se falhar, tentamos de novo em 1 min, 5 min, 30 min, 2 h e 6 h. Depois disso a entrega vai para a fila morta: listem em GET /v1/webhook-deliveries?status=dead e reenviem com POST /v1/webhook-deliveries/{id}/resend. Usem X-Canal-Delivery para não processar o mesmo evento duas vezes.
Se preferirem não receber webhook, peçam o modo só guardar: tudo fica disponível em GET /v1/messages e GET /v1/conversations.
5. Erros
Formato: { "error": { "code", "message", "param", "errors": [...] } }. O code é estável; a message é para gente ler.
Nossos códigos
| HTTP | code | O que fazer |
|---|---|---|
| 401 | unauthorized / invalid_token | Token ausente, vencido ou de credencial revogada. Peça outro em /oauth/token. |
| 403 | insufficient_scope | A credencial não tem o escopo da rota (ex.: messages:send). Peça a credencial certa. |
| 403 | ip_not_allowed | A chamada saiu de um IP fora da lista da credencial. |
| 402 | company_suspended | Empresa suspensa por pendência comercial. Fale com a Soluções de IA; nada foi apagado. |
| 429 | rate_limited | Limite por minuto da credencial. Espere o tempo de Retry-After. |
| 422 | invalid_phone | Telefone fora do padrão: só dígitos com DDI (5531999990000). |
| 422 | template_not_found | Template não existe nesta conta/idioma. Rode POST /v1/templates/sync ou confira o nome. |
| 422 | template_not_approved | Template pendente, rejeitado ou pausado na Meta. |
| 422 | template_variables_mismatch | Variável faltando, a mais ou no tipo errado (dinheiro em centavos, data AAAA-MM-DD). Veja errors[] e o /schema. |
| 422 | media_invalid | Cabeçalho de mídia ausente, tipo errado, url sem https ou media_id vencido. |
| 422 | contact_opted_out | O contato pediu para sair. Não envie (só se ele pedir para voltar: DELETE .../opt-out). |
| 422 | outside_window | Texto livre fora das 24 h depois da última mensagem do contato. Use template. |
| 422 | number_not_found / number_required | Número não é da empresa, ou a empresa tem vários e faltou from. |
| 422 | idempotency_conflict | client_message_id já usado com outro conteúdo. |
| 409 | idempotency_in_progress | A mesma chave ainda está sendo processada. Tente em alguns segundos. |
| 404 | event_not_configured | Evento sem template configurado em /v1/event-triggers. |
| 422 / 502 | meta_error | A Meta recusou (meta_error traz o código) ou ficou fora (502). |
| 202 | meta_timeout (status unknown) | A Meta não respondeu a tempo. NÃO reenvie: o status chega pelo webhook. |
Principais códigos da Meta (em error.meta_error)
| Código | Significa | O que fazer |
|---|---|---|
131026 | Mensagem não entregável | Número sem WhatsApp, app muito antigo ou contato não aceitou os termos. Não insista; confirme o número por outro canal. |
131042 | Problema de pagamento | A conta Meta de vocês está sem meio de pagamento válido. Corrijam no Gerenciador de Negócios. Avisamos quando aparece. |
131049 | Marketing não entregue (saúde do ecossistema) | A Meta limitou marketing para esse contato. Não reenvie logo; espere dias ou use utilidade quando couber. |
131047 | Fora da janela de 24 h | Só template reabre a conversa. |
131056 | Muitas mensagens para o mesmo contato | Espere alguns minutos entre envios ao mesmo número. |
130429 | Limite de vazão | Muitas mensagens por segundo. Distribua o disparo. |
131048 | Limite por spam | Qualidade caiu (bloqueios/denúncias). Reduza o volume e revise o conteúdo. |
132000 | Quantidade de parâmetros errada | O template mudou ou faltou variável. Consulte o /schema. |
132001 | Template não existe | Nome ou idioma errado, ou template apagado. |
132012 | Formato de parâmetro errado | Ex.: cabeçalho de documento sem documento. |
131051 | Tipo de mensagem não suportado | Revise o type enviado. |
133010 | Número não registrado na Cloud API | Fale com a Soluções de IA (registro do número). |
190 | Token da Meta inválido | Fale com a Soluções de IA (reconexão do número). |
368 | Bloqueio temporário por política | Conta restrita pela Meta. Fale com a Soluções de IA. |
6. Limites
- Nossa API: 120 requisições por minuto por credencial (ajustável). Passou, 429 com
Retry-After. Emissão de token: 30 tentativas por minuto por client_id. - Limite da Meta por número (tier): quantos contatos diferentes o número pode iniciar em 24 h corridas: 250, depois 1 mil, 10 mil, 100 mil e ilimitado. Sobe com a verificação da empresa e boa qualidade; o
dry_runmostra quanto resta hoje. - Qualidade: verde, amarela ou vermelha, pelos bloqueios e denúncias dos contatos. Vermelha pode baixar o tier ou pausar templates.
- Vazão: a Meta aceita por volta de 80 mensagens por segundo por número; distribua campanhas grandes.
- Tamanhos: texto até 4.096 caracteres; documento até 100 MB (por url); imagem 5 MB; vídeo 16 MB; upload por
/v1/mediaaté ~4 MB por requisição. - Webhook: resposta em até 8 s; 5 retentativas.
7. Referência completa
Todos os endpoints, campos e respostas, gerados da especificação OpenAPI 3.1: abrir a referência (botão “Test request” para testar no ambiente de teste com uma credencial sandbox) ou baixar o openapi.json para gerar cliente no Postman/Insomnia.
8. Changelog
- 1.0.0 (18/11/2026, ambiente de teste): primeira versão. OAuth2 client_credentials com escopos; envio de template com variáveis tipadas, cabeçalho de documento e botões; texto e interativos na janela; dry_run; idempotência por client_message_id; mídia; disparo por evento; opt-out; webhooks assinados com retentativa e fila morta; cadastro incorporado; credencial sandbox.
- Próximas (fase 2): campanhas, fluxos, caixa de conversas, rastreio de links (track_links), opt-in de marketing, PDF gerado a partir de modelo.