Ambiente de teste: dados fictícios, nenhuma mensagem vai para a Meta ou para pessoas reais.
Canal API Oficial

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 from com o phone_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

  1. Nós criamos uma credencial para vocês: client_id (público) e client_secret (mostrado uma vez). Guardem o segredo no cofre do servidor, nunca no navegador ou no aplicativo.
  2. Troquem a credencial por um token de acesso de 1 hora em POST /oauth/token (OAuth2 client_credentials).
  3. Mandem o token em toda chamada: Authorization: Bearer <access_token>. Reaproveitem até perto de vencer; recebeu 401, peçam outro.
Sistema do clienteCanal API OficialBanco do CanalPOST /oauth/token (client_id + client_secret)confere segredo (hash),validade, IP permitido eempresa ativagrava token (só o hash) + auditoria200 access_token, expires_in 3600, scopeGET/POST /v1/... Authorization: Bearertoken vivo? escopo darota? limite por minuto?resposta (ou 401 / 403 / 429)
Autenticação: credencial vira token de 1 hora
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

EscopoLibera
messages:sendEnviar mensagens, eventos, mídia e registrar opt-out
messages:readConsultar mensagens, conversas, números e baixar mídia recebida
templates:readListar templates, schema, prévia e eventos configurados
templates:writeCriar templates e configurar disparo por evento
webhooks:manageCadastrar webhooks e reenviar entregas
numbers:manageConectar 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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST /v1/messages (template + variáveis)token, escopo, opt-out,template aprovado, tiposdas variáveis, cabeçalhoe botões202 { id, status: queued }POST /{phone_number_id}/messageswamid (aceita)entrega a mensagemwebhook message.queued
Envio de template
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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatocontato escrevewebhook da Meta (abre a janela)webhook message.receivedPOST /v1/messages type=text | interactivejanela aberta? limitesde botões/listaenviaentrega
Texto na janela
{ "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[].

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST /v1/messages?dry_run=truemesmas validações doenvio; nada é gravadonem vai para a Meta200 valid + categoria + limite | 422 errors[]
dry_run: valida e não envia
{ "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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST /v1/templatesPOST /{waba_id}/message_templatesid + PENDING201 status pendingMeta revisa (minutos ahoras)webhook message_template_status_updatewebhook template.status (approved / rejected)
Criação de template e aprovação
{
  "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}.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST /v1/media (url ou base64)valida tipo e tamanho;mesmo arquivo?reaproveitaPOST /{phone_number_id}/mediaid da mídia na Meta201 media_id (vale 30 dias)POST /v1/messages header.document.media_idtemplate com documentoPDF chega no cabeçalho
PDF no cabeçalho com 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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST /v1/event-triggers (uma vez)POST /v1/events { event, to, variables }acha o template doevento e valida asvariáveis202 { id, event, status: queued }envia o templateentrega
Disparo por evento
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" } }
EventoQuando
message.queuedAceitamos a mensagem
message.sent / message.delivered / message.readA Meta enviou / chegou no aparelho / o contato leu
message.failedFalhou; data.meta_error traz o código da Meta
message.receivedO contato mandou mensagem (texto, mídia, localização...)
button.clickedClique em botão de template ou de mensagem interativa (payload e mensagem de origem)
contact.opted_outO contato pediu para sair (SAIR, PARAR, STOP) ou vocês registraram
template.statusTemplate aprovado, rejeitado, pausado
number.qualityMudanç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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatocontato responde / clica no botãoPOST webhook (X-Hub-Signature-256)confere assinatura,grava o evento cru, achaa empresa pelophone_number_id200message.received (+ button.clicked / contact.opted_out)
Resposta e botão

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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatostatus sentmessage.sentaparelho recebeu / contato leustatus delivered / readgrava na linha do tempo;status nunca regridemessage.delivered / message.readou: failed + código (ex.: 131026)message.failed { meta_error }
Status

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.

Sistema do clienteCanal API OficialMeta (Cloud API)WhatsApp do contatoPOST evento (tentativa 1)erro ou sem resposta em 8 sagenda: 1 min, 5 min, 30min, 2 h, 6 hnovas tentativas (mesmo X-Canal-Delivery)esgotou: fila morta(nada se perde)POST /v1/webhook-deliveries/{id}/resendentrega de novo
Reenvio de webhook

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

HTTPcodeO que fazer
401unauthorized / invalid_tokenToken ausente, vencido ou de credencial revogada. Peça outro em /oauth/token.
403insufficient_scopeA credencial não tem o escopo da rota (ex.: messages:send). Peça a credencial certa.
403ip_not_allowedA chamada saiu de um IP fora da lista da credencial.
402company_suspendedEmpresa suspensa por pendência comercial. Fale com a Soluções de IA; nada foi apagado.
429rate_limitedLimite por minuto da credencial. Espere o tempo de Retry-After.
422invalid_phoneTelefone fora do padrão: só dígitos com DDI (5531999990000).
422template_not_foundTemplate não existe nesta conta/idioma. Rode POST /v1/templates/sync ou confira o nome.
422template_not_approvedTemplate pendente, rejeitado ou pausado na Meta.
422template_variables_mismatchVariável faltando, a mais ou no tipo errado (dinheiro em centavos, data AAAA-MM-DD). Veja errors[] e o /schema.
422media_invalidCabeçalho de mídia ausente, tipo errado, url sem https ou media_id vencido.
422contact_opted_outO contato pediu para sair. Não envie (só se ele pedir para voltar: DELETE .../opt-out).
422outside_windowTexto livre fora das 24 h depois da última mensagem do contato. Use template.
422number_not_found / number_requiredNúmero não é da empresa, ou a empresa tem vários e faltou from.
422idempotency_conflictclient_message_id já usado com outro conteúdo.
409idempotency_in_progressA mesma chave ainda está sendo processada. Tente em alguns segundos.
404event_not_configuredEvento sem template configurado em /v1/event-triggers.
422 / 502meta_errorA Meta recusou (meta_error traz o código) ou ficou fora (502).
202meta_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ódigoSignificaO que fazer
131026Mensagem não entregávelNúmero sem WhatsApp, app muito antigo ou contato não aceitou os termos. Não insista; confirme o número por outro canal.
131042Problema de pagamentoA conta Meta de vocês está sem meio de pagamento válido. Corrijam no Gerenciador de Negócios. Avisamos quando aparece.
131049Marketing 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.
131047Fora da janela de 24 hSó template reabre a conversa.
131056Muitas mensagens para o mesmo contatoEspere alguns minutos entre envios ao mesmo número.
130429Limite de vazãoMuitas mensagens por segundo. Distribua o disparo.
131048Limite por spamQualidade caiu (bloqueios/denúncias). Reduza o volume e revise o conteúdo.
132000Quantidade de parâmetros erradaO template mudou ou faltou variável. Consulte o /schema.
132001Template não existeNome ou idioma errado, ou template apagado.
132012Formato de parâmetro erradoEx.: cabeçalho de documento sem documento.
131051Tipo de mensagem não suportadoRevise o type enviado.
133010Número não registrado na Cloud APIFale com a Soluções de IA (registro do número).
190Token da Meta inválidoFale com a Soluções de IA (reconexão do número).
368Bloqueio temporário por políticaConta 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_run mostra 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/media até ~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.