Construa sobre o WhatsApp oficial. Não em volta dele.

Uma eclusa entre o seu código e a Meta.

Uma eclusa iguala dois níveis antes de dar passagem. A Eclusa faz o mesmo com cada mensagem: valida, persiste e só então deixa passar, nos dois sentidos.

POST eclusa.api.br/v1/messages
Idempotency-Key: pedido-48213
{ "to": "+5511999999999",
  "type": "template",
  "template": "confirmacao_pedido",
  "variables": { "pedido": "48213",
                 "entrega": "quinta" } }

await client.messages.send({
  to: '+5511999999999',
  type: 'template',
  template: 'confirmacao_pedido',
  variables: { pedido: '48213',
               entrega: 'quinta' },
  idempotencyKey: 'pedido-48213',
});

# agente, ferramenta tipada
enviar_template({
  "to": "+5511999999999",
  "template": "confirmacao_pedido",
  "variables": { "pedido": "48213",
                 "entrega": "quinta" }
})

Passo a passo, em detalhe.

1. 

   passo 1 de 3

   Seu sistema envia o evento

   Seu sistema envia um evento, como um pedido criado ou um pagamento aprovado. Ele parte rumo à eclusa.

2. 

   passo 2 de 3

   A câmara central confere e guarda

   Na câmara central, as comportas se fecham, o nível se ajusta, o evento é validado e guardado. O visto confirma que nada se perde.

3. 

   passo 3 de 3

   O evento chega ao WhatsApp e a resposta volta

   A comporta de saída se abre, o evento segue para o WhatsApp pela Meta e a resposta do cliente volta pelo mesmo caminho.

1. 1 Entra

   Seu produto chama a API, o SDK ou o MCP. A Eclusa autentica a conta de serviço e resolve a organização certa.

2. 2 Iguala

   Permissão, consentimento, janela de atendimento e template são checados antes de qualquer envio. A chave de idempotência impede a mensagem duplicada. O comando é persistido.

3. 3 Passa

   A mensagem segue para a API oficial da Meta. Status de envio, entrega, leitura e falha voltam como eventos.

4. 4 Volta

   Cada webhook da Meta tem a assinatura verificada, é persistido antes do ACK, deduplicado num único evento e entregue ao seu endpoint com o mesmo event_id.

Montante: seu produto, sua API, seu agente. Câmara: Eclusa valida, persiste e dá passagem. Jusante: WhatsApp oficial. Você envia e recebe. O que acontece dentro da câmara fica registrado e pode ser reprocessado.

Quatro portas para o mesmo contrato.

A mesma autenticação, a mesma idempotência e os mesmos erros, de qualquer lado que você entrar.

curl -X POST https://eclusa.api.br/v1/messages \
  -H "Authorization: Bearer $ECLUSA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"+5511999999999",
     "type":"text",
     "text":{"body":"Olá."}}'

// POST https://seu-produto.com/webhook
// assinatura e timestamp nos headers
{
  "event_id": "evt_01J9ZK4T8Q",
  "type": "message.status.delivered",
  "version": "2026-09",
  "occurred_at": "2026-09-22T14:03:11Z",
  "data": { "...": "..." }
}

import { Eclusa } from '@eclusahq/sdk';
const client = new Eclusa({ apiKey });
await client.messages.send({
  to: '+5511999999999',
  type: 'text',
  text: { body: 'Olá.' },
});

// POST https://seu-produto.com/webhook
// assinatura e timestamp nos headers
{
  "event_id": "evt_01J9ZK4T8Q",
  "type": "message.status.delivered",
  "version": "2026-09",
  "occurred_at": "2026-09-22T14:03:11Z",
  "data": { "...": "..." }
}

from eclusahq import Eclusa

client = Eclusa(api_key=os.environ["ECLUSA_API_KEY"])
client.messages.send(
    to="+5511999999999",
    type="text",
    text={"body": "Olá."}
)

// POST https://seu-produto.com/webhook
// assinatura e timestamp nos headers
{
  "event_id": "evt_01J9ZK4T8Q",
  "type": "message.status.delivered",
  "version": "2026-09",
  "occurred_at": "2026-09-22T14:03:11Z",
  "data": { "...": "..." }
}

{
  "mcpServers": {
    "eclusa": {
      "command": "npx",
      "args": ["@eclusahq/mcp"],
      "env": { "ECLUSA_API_KEY": "..." }
    }
  }
}

# ferramentas expostas ao agente
listar_canais
consultar_saude_e_limites
enviar_mensagem
enviar_template
consultar_janela
listar_templates
consultar_status_mensagem
buscar_evento
repetir_entrega

// POST https://seu-produto.com/webhook
{
  "event": "message.received",
  "from":  "+5511999999999",
  "body":  "Olá!",
  "ts":    1750000000
}

// POST https://seu-produto.com/webhook
// assinatura e timestamp nos headers
{
  "event_id": "evt_01J9ZK4T8Q",
  "type": "message.status.delivered",
  "version": "2026-09",
  "occurred_at": "2026-09-22T14:03:11Z",
  "data": { "...": "..." }
}

Documentação completa (em breve).

Mensageria falha. A Eclusa foi desenhada para falhar direito.

Duplicação, atraso, reordenação, token revogado e webhook fora do ar são rotina no WhatsApp. Cada caso já tem um comportamento definido no contrato.

1. Envie duas vezes. Entregue uma.

   Todo comando mutável exige chave de idempotência. A mesma chave com o mesmo payload devolve o resultado original. A mesma chave com payload diferente devolve conflito. Nada de mensagem dupla porque o seu retry foi rápido demais.

   curl -X POST https://eclusa.api.br/v1/messages \
     -H "Authorization: Bearer $ECLUSA_API_KEY" \
     -H "Idempotency-Key: pedido-48213-confirmacao" \
     -d '{ ... }'
   # mesma chave, mesmo payload     → 200, resultado original
   # mesma chave, payload diferente → 409, conflito

2. Nenhum ACK antes de persistir.

   Um evento da Meta só é confirmado depois de gravado de forma durável. Entradas repetidas viram um único evento canônico. Seu endpoint recebe entrega at-least-once, sempre com o mesmo event_id, então deduplicar do seu lado é trivial.

   // POST https://seu-produto.com/webhook
   // assinatura e timestamp nos headers
   {
     "event_id": "evt_01J9ZK4T8Q",
     "type": "message.status.delivered",
     "version": "2026-09",
     "occurred_at": "2026-09-22T14:03:11Z",
     "data": { "...": "..." }
   }

3. Retry com critério. Dead-letter queue com endereço.

   Falha transitória (rede, timeout, 429, 5xx da Meta) é repetida com backoff exponencial e jitter. Erro de validação ou de política é recusado na hora, antes de entrar na fila, com a correção sugerida. Só as falhas assíncronas que esgotam as tentativas vão para a dead-letter queue, onde você as encontra.

4. Replay quando você quiser.

   Busque, inspecione e reprocesse qualquer evento pelo painel ou pela API, dentro da retenção de conteúdo configurada.

5. Erros que dizem o que fazer.

   Toda resposta de erro traz código, categoria, se vale tentar de novo, request_id, o código original da Meta quando existe e a ação sugerida.

   {
     "error": {
       "code": "template_required",
       "category": "policy",
       "retryable": false,
       "request_id": "req_7Hq2kd91",
       "meta_code": null,
       "action": "Fora da janela de atendimento. Envie um template aprovado."
     }
   }

Tudo o que acontece no canal, num lugar que você consegue ler.

O código é headless. A operação tem painel: saúde dos canais, templates, consentimentos, eventos e chaves de todos os clientes, com o mesmo modelo de dados.

• Visão geralSaúde dos canais, falhas e consumo, num relance.
• CanaisNúmeros, estado da conexão, qualidade e limites de cada um.
• TemplatesCrie, submeta e acompanhe: aprovado, em análise, pausado ou rejeitado.
• EventosBusque qualquer evento, veja cada tentativa de entrega e faça replay.
• ConsentimentosOpt-in e opt-out por contato, com a evidência guardada.
• DesenvolvedoresChaves por cliente, rotação sem interrupção, webhooks, SDKs, MCP e sandbox.

Seus clientes, sua operação. Os ativos continuam deles.

Feita para quem opera muitas empresas. Cada cliente autoriza os próprios ativos da Meta, e você recebe acesso delegado, não a posse.

1. Crie seu workspace de parceiro.
2. Crie ou convide a empresa cliente.
3. O representante da empresa autoriza os ativos da Meta dela.
4. Você recebe acesso delegado.
5. Configure API, webhook, MCP ou integração guiada.
6. Acompanhe saúde e eventos de todos os clientes numa visão só.