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

Como o seu sistema se integra ao Canal API Oficial

Guia de uma página para quem vai programar a integração. Referência completa em /docs. Endereço da API: https://canalapioficial.solucoesdeia.com.

O que vocês recebem de nós

1. Pegar o token de acesso

Troque a credencial por um token que vale 1 hora. Reaproveite o token até perto de vencer; quando receber 401, peça outro.

curl -s -X POST https://canalapioficial.solucoesdeia.com/oauth/token \
  -d grant_type=client_credentials \
  -d client_id=SEU_CLIENT_ID \
  -d client_secret=SEU_CLIENT_SECRET

# resposta
{"access_token":"cat_live_...","token_type":"Bearer","expires_in":3600,"scope":"messages:send messages:read ..."}

Cada credencial tem escopos (o que pode fazer), limite por minuto e, se quiserem, lista de IPs. Uma credencial revogada para de funcionar na hora.

2. Conferir os templates

Mensagem que começa a conversa precisa de template aprovado pela Meta. GET /v1/templates?status=approved lista os aprovados e GET /v1/templates/{id}/schema diz quais variáveis cada um pede, de que tipo e quais são obrigatórias. Templates novos: POST /v1/templates (a aprovação chega no webhook template.status).

3. Enviar

curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/messages \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{
    "to": "5561999990000",
    "client_message_id": "reserva-4471-confirmacao",
    "template": {
      "name": "confirmacao_reserva",
      "language": "pt_BR",
      "variables": { "nome": "Carla", "checkin": "2026-12-20", "valor": 128000 },
      "buttons": { "url_suffix": "4471" }
    },
    "metadata": { "reserva": "4471" }
  }'

# resposta 202
{"id":"0d7e...","status":"queued","to":"5561999990000","client_message_id":"reserva-4471-confirmacao", ...}

4. Receber os eventos no seu sistema

Cadastre o endereço do seu sistema em POST /v1/webhooks (ou peça para nós). Mandamos um POST para cada evento: message.queued, message.sent, message.delivered, message.read, message.failed (com o código de erro da Meta), message.received, button.clicked, contact.opted_out, template.status.

Responda 200 em até 8 segundos e processe depois. Se o seu sistema estiver fora, tentamos de novo em 1 min, 5 min, 30 min, 2 h e 6 h; nada se perde e dá para reenviar depois.

// Node.js: conferir a assinatura do webhook
import { createHmac, timingSafeEqual } from "node:crypto";

function assinaturaValida(corpoCru, cabecalhos, segredo) {
  const ts = cabecalhos["x-canal-timestamp"];
  const esperado = "v1=" + createHmac("sha256", segredo).update(ts + "." + corpoCru).digest("hex");
  const veio = cabecalhos["x-canal-signature"] ?? "";
  const recente = Math.abs(Date.now() / 1000 - Number(ts)) < 300; // até 5 minutos
  return recente && veio.length === esperado.length && timingSafeEqual(Buffer.from(veio), Buffer.from(esperado));
}

Recuse (401) qualquer chamada com assinatura errada ou horário com mais de 5 minutos de diferença. Se preferirem não receber webhook, tudo fica guardado e pode ser consultado em GET /v1/messages.

5. Disparo por evento (opcional)

Em vez de montar a mensagem, o sistema de vocês avisa o que aconteceu e nós usamos o template configurado para aquele evento (POST /v1/event-triggers):

curl -s -X POST https://canalapioficial.solucoesdeia.com/v1/events \
  -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
  -d '{"event":"checkout_realizado","to":"5561999990000","client_message_id":"checkout-4471",
       "variables":{"nome":"Carla","total":245000,"link_pagamento":"pix-4471"}}'

Regras que evitam problema