Documentação da API

O ConnectaWhats fica entre a WhatsApp Cloud API da Meta e o seu sistema (n8n, CRM, backend próprio ou agente de IA). Ele recebe os eventos da Meta e entrega no seu webhook, já normalizados e assinados. Na outra direção, você envia mensagens por uma API REST simples ou pelo servidor MCP, sem lidar com tokens da Meta.

Conceitos

Respostas e erros

• Sucesso nos envios: { "success": true, ... }. Listagens: { "data": [...], "total": n }.
• Erro: status 4xx/5xx com { "error": "mensagem", "detail"?: ..., "details"?: ..., "issues"?: [...] }. issues explica o que falta num template; details traz os campos inválidos.
• 401 token ausente ou inválido · 403 chave sem a permissão necessária · 404 recurso inexistente ou de outro usuário (o sistema não revela recursos alheios) · 422 recurso existe mas não pode ser usado assim · 502 a Meta recusou: metaCode e metaMessage trazem o código e a mensagem dela.

Toda chamada leva Authorization: Bearer <token>. Existem dois tipos de token:

1. Chave de API (recomendado)

Criada em Meu perfil → Chaves de API. Começa com cwk_ e é mostrada uma única vez — guarde num cofre de segredos. Cada chave tem permissões e pode ficar restrita a um único tenant. Revogar a chave corta o acesso na hora.

2. Secret do tenant ou do número (só para envio)

O webhookSecret do tenant (ou o do número, quando ele tem webhook próprio ativo) também é aceito, mas apenas nas rotas de envio de /api/tenants/:tenantId/phones/:phoneId/... (send, send-text, send-media, send-interactive, send-template, mark-read, typing, media) e na leitura de templates. É o mesmo valor que o sistema usa para assinar os webhooks, então serve para o fluxo responder sem precisar de outra credencial. O secret do número vale só para aquele número.

Isolamento

• Você só enxerga os seus tenants. Um id de outro usuário devolve 404.
• Uma chave restrita a um tenant recebe 404 em qualquer outro, inclusive no MCP.
• Dê a cada integração a menor permissão possível (ex.: um painel de BI só precisa de read).

Do zero ao primeiro envio em três chamadas:

1. Descobrir o tenant e o número

curl https://connecta-api.riapp.app/api/tenants \
  -H "Authorization: Bearer cwk_SUA_CHAVE"

curl https://connecta-api.riapp.app/api/tenants/TENANT_ID/phones \
  -H "Authorization: Bearer cwk_SUA_CHAVE"

Use o id do tenant e o id do número (não o metaPhoneId) nas próximas chamadas.

2. Enviar uma mensagem

curl -X POST https://connecta-api.riapp.app/api/tenants/TENANT_ID/phones/PHONE_ID/send \
  -H "Authorization: Bearer cwk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -d '{ "to": "5511999999999", "type": "text", "text": "Olá! Tudo certo?" }'

{ "success": true, "wamid": "wamid.HBgN...", "message": { "id": "clx...", "status": "sent", ... } }

3. Receber as respostas

Configure a URL do seu sistema no tenant (ou no número) e trate os eventos descritos em Receber eventos.

O ConnectaWhats faz um POST JSON na sua URL a cada evento. Você não precisa configurar nada na Meta: o callback dela aponta sempre para o ConnectaWhats, que repassa para você.

Para onde vão os eventos

• Webhook do tenant (padrão): URL e secret definidos na tela do tenant. Recebe os eventos de todos os números.
• Webhook do número (opcional): na aba Números → Webhook. Quando ativo, os eventos daquele número vão para a URL dele, assinados com o secret dele.
• O campo wa_bridge.webhookScope diz qual foi usado: "tenant" ou "phone".
• Eventos de conta e de template (account/template) vão sempre para o webhook do tenant.

Filtros do tenant decidem o que é enviado:

Headers, assinatura e tentativas

• Responda com status 2xx em até 10 segundos. Processamentos longos (IA, transcrição) devem rodar depois de responder.
• Se falhar, o sistema tenta mais 2 vezes (esperas de 1s e 3s). Cada tentativa fica registrada nos logs de webhook.
• A mesma mensagem pode chegar duas vezes em caso de nova tentativa: use message.id (wamid) para não processar repetido.

import crypto from 'node:crypto'
import express from 'express'

const app = express()
// importante: guardar o corpo BRUTO, sem reformatar o JSON
app.post('/whatsapp', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto.createHmac('sha256', process.env.CONECTAWHATS_SECRET)
    .update(req.body)                // Buffer com o corpo exato recebido
    .digest('hex')
  const received = req.get('X-WA-Bridge-Signature') ?? ''
  const ok = received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected))
  if (!ok) return res.sendStatus(401)

  res.sendStatus(200)                // responde logo
  const event = JSON.parse(req.body.toString('utf8'))
  queue.push(event)                  // processa depois
})

Mensagem recebida — message

{
  "channel": "WHATSAPP",
  "event": "message",
  "humanMode": false,
  "leadStage": "FRIO",
  "leadSource": { "id": "clx...", "name": "Promo Black Friday" },
  "tenant": "slug-do-tenant",
  "phoneNumber": "+5511999999999",
  "contact": { "name": "João", "waId": "5511988887777", "userId": "BR.1234567890", "username": null },
  "from": "5511988887777",
  "message": {
    "id": "wamid.HBg...", "from": "5511988887777", "from_user_id": "BR.1234567890",
    "type": "text", "text": { "body": "Olá" }
  },
  "text": "Olá",
  "receivedAt": "2026-11-10T12:00:00.000Z",
  "wa_bridge": {
    "tenantId": "clx...",
    "phoneNumberId": "clx...",
    "phoneNumberMetaId": "1234567890",
    "wabaId": "9876543210",
    "messageId": "clx...",
    "webhookScope": "tenant"
  }
}

Campos extras, presentes quando se aplicam:

Mídia recebida

O arquivo é baixado da Meta na hora e guardado no storage. O evento traz um link pronto:

"media": {
  "type": "audio",
  "url": "https://...r2.cloudflarestorage.com/...&X-Amz-Signature=...",
  "expiresAt": "2026-11-11T12:00:00.000Z",
  "mimeType": "audio/ogg",
  "size": 17759,
  "voice": true,
  "downloadEndpoint": "https://connecta-api.riapp.app/api/tenants/TENANT_ID/messages/MESSAGE_ID/media"
}

• media.url baixa direto, sem header nenhum, por 24h.
• Depois disso, chame GET downloadEndpoint com o seu Bearer: ele redireciona para um link novo (ou devolve { url } com ?json=1).
• Áudio de voz chega como audio/ogg (opus). Converta se a sua API de transcrição não aceitar esse formato.

Status de entrega — status

{
  "channel": "WHATSAPP",
  "event": "status",
  "status": { "id": "wamid...", "status": "read", "timestamp": "1762780000", "errors": [], "pricing": { ... } },
  "wa_bridge": { "tenantId": "...", "phoneNumberId": "...", "messageId": "clx..." }
}

status: sent → delivered → read (ou played para áudio). Em failed, veja status.errors[0] (code e message da Meta).

Conta e templates — account / template

{ "event": "message_template_status_update", "wabaId": "9876543210", "value": { "event": "APPROVED", "message_template_name": "pedido_enviado", ... } }

event é o campo da Meta: message_template_status_update (aprovado/rejeitado),template_category_update, phone_number_quality_update, account_update, account_alerts.

Coexistência (número também usado no app do celular)

Resposta de WhatsApp Flow

Quando o cliente envia um formulário, o evento message traz o bloco flow:

"flow": {
  "id": "clx...", "name": "Orçamento casamento", "metaFlowId": "1234567890",
  "data":    { "nome_dos_noivos": "Ana e Pedro", "data_do_casamento": "2027-03-20", "periodo": "1_tarde" },
  "answers": { "Nome dos noivos": "Ana e Pedro", "Data do casamento": "2027-03-20", "Período": "Tarde" }
}

answers usa os rótulos dos campos e as opções em texto — é o formato ideal para CRM e IA. data traz os nomes técnicos.

Facebook e Instagram

{
  "channel": "INSTAGRAM",
  "tenant": "slug-do-tenant",
  "contact": { "name": null, "id": "1234567890123" },
  "message": { "mid": "m_abc...", "text": "oi", "attachments": [{ "type": "image", "payload": { "url": "https://scontent..." } }] },
  "receivedAt": "2026-11-10T12:00:00.000Z",
  "wa_bridge": { "tenantId": "clx...", "channelId": "clx...", "replyEndpoint": "https://connecta-api.riapp.app/api/tenants/.../social-channels/.../send" }
}

channel é FACEBOOK ou INSTAGRAM. As URLs de anexo já são públicas.

Todas as rotas ficam em /api/tenants/:tenantId/phones/:phoneId/.... O destinatário vai em to: telefone com DDI ou BSUID (ex.: BR.1234567890) — a API reconhece qual é. recipient continua aceito para o BSUID. Use replyTo (wamid) para citar uma mensagem.

header de botões/lista/cta: { "type": "text", "text": "..." } ou { "type": "image" | "video" | "document", "image" | "video" | "document": { "link" | "id" } }.

{ "to": "5511999999999", "type": "text", "text": "Segue o link", "previewUrl": true, "replyTo": "wamid.HBg..." }

{ "to": "5511999999999", "type": "document", "link": "https://exemplo.com/boleto.pdf", "filename": "boleto.pdf", "caption": "Seu boleto" }

{ "to": "BR.1234567890", "type": "buttons", "body": "Confirma o horário?",
  "buttons": [{ "id": "sim", "title": "Sim" }, { "id": "nao", "title": "Não" }] }

{ "to": "5511999999999", "type": "list", "body": "Escolha o plano", "buttonText": "Ver planos",
  "sections": [{ "title": "Planos", "rows": [{ "id": "basic", "title": "Básico" }, { "id": "pro", "title": "Pro", "description": "Mais usado" }] }] }

{ "to": "5511999999999", "type": "cta_url", "body": "Acompanhe seu pedido", "buttonText": "Rastrear", "url": "https://loja.com/r/123" }

{ "to": "5511999999999", "type": "flow", "flowId": "clx...", "body": "Preencha o orçamento", "buttonText": "Abrir formulário" }

Templates (fora da janela de 24h)

{
  "to": "5511999999999",
  "template": {
    "name": "pedido_enviado",
    "language": "pt_BR",
    "header": { "type": "image", "link": "https://exemplo.com/produto.jpg" },
    "body": ["João", "A123"],
    "buttons": [{ "type": "url", "index": 0, "text": "A123" }]
  }
}

• Template de autenticação (OTP): basta "body": ["123456"]; o código é repetido no botão automaticamente.
• Se faltar algo, a resposta é 400 com issues explicando (ex.: “botão 0 exige o sufixo da URL”).
• Formato legado também aceito: { "to", "templateName", "languageCode", "parameters": ["v1", "v2"] }.

Upload de mídia

curl -X POST https://connecta-api.riapp.app/api/tenants/TENANT_ID/phones/PHONE_ID/media \
  -H "Authorization: Bearer cwk_SUA_CHAVE" \
  -F "file=@catalogo.pdf"

Marcar como lida e “digitando…”

Rotas legadas (continuam funcionando)

Facebook e Instagram

Base: /api/tenants/:tenantId/social-channels/:channelId — o channelId vem em wa_bridge.channelId no evento.

Configurações do número (somente leitura pela API)

{ "humanMode": true, "leadStage": "MANUAL_QUENTE", "leadNote": "Pediu orçamento para 150 convidados" }

Mensagens

Campanhas e Flows são criados no painel. Pela API você acompanha o progresso e lê as respostas.

Informa à Meta que um lead que veio de anúncio Click-to-WhatsApp avançou (lead qualificado, venda). Os anúncios passam a otimizar por resultado real.

{ "eventName": "Purchase", "value": 15000, "currency": "BRL", "reference": "contrato-123" }

Os filtros abaixo valem para todas as rotas de métricas e custos:

Logs de entrega do webhook

curl "https://connecta-api.riapp.app/api/metrics/overview?period=30d" -H "Authorization: Bearer cwk_SUA_CHAVE"

O MCP (Model Context Protocol) expõe as operações do ConnectaWhats como ferramentas que um modelo de linguagem chama sozinho. Conectado ao MCP, um agente de IA consegue ler conversas, responder clientes, consultar templates e extrair métricas da operação, sem você programar cada chamada HTTP.

Ferramentas

• period: today, 24h, 7d (padrão), 30d, 90d. from/to em ISO 8601 têm precedência.
• Ferramentas com phoneId aceitam o id interno; as de métricas aceitam também o phone_number_id da Meta.
• Erros voltam como resultado da ferramenta com isError: true e a explicação em texto, para o modelo corrigir e tentar de novo.

Agente de IA com as ferramentas do ConnectaWhats

• No workflow, adicione um nó AI Agent com o modelo de sua preferência.
• Em Tools, adicione o nó MCP Client Tool.
• Endpoint: https://connecta-api.riapp.app/mcp
• Server Transport: HTTP Streamable
• Authentication: Bearer Auth, com uma credencial cujo token é a chave cwk_....
• Tools to Include: Selected e marque só as que o agente precisa (ex.: get_messages, send_message, update_contact). Menos ferramentas = escolhas mais certeiras do modelo.

Você atende clientes da empresa pelo WhatsApp usando as ferramentas do ConnectaWhats.
- tenantId: {{ $json.wa_bridge.tenantId }}
- phoneId: {{ $json.wa_bridge.phoneNumberId }}
- cliente: {{ $json.from }} ({{ $json.contact.name }})
Antes de responder, leia as últimas mensagens com get_messages (contact = o cliente acima).
Responda com send_message (type "text", to = o cliente acima — telefone ou BSUID, use exatamente como veio). Se o cliente pedir um humano, chame
update_contact com humanMode = true e avise que um atendente vai continuar.

Fluxo completo de atendimento

• Webhook (trigger) recebe o evento do ConnectaWhats. Valide o header Authorization com Header Auth.
• IF {{ $json.humanMode }} é true → encerra (um atendente está na conversa).
• HTTP Request POST .../mark-read com typing: true (opcional, best-effort).
• Se houver media, baixe por {{ $json.media.url }} (Response Format = File) e transcreva/analise.
• AI Agent com o MCP Client Tool responde e age (modo humano, estágio do lead, templates).

Sem agente: nó HTTP Request

Para chamadas fixas (ex.: enviar um template quando um pedido muda de status) use a API REST direto:

• Method POST, Body JSON.
• URL: ={{ "https://connecta-api.riapp.app/api/tenants/" + $json.wa_bridge.tenantId + "/phones/" + $json.wa_bridge.phoneNumberId + "/send" }}
• Authentication: Generic → Header Auth, nome Authorization, valor Bearer cwk_... (ou o secret do tenant).
• Destinatário: "to": "{{ $json.from }}" no corpo. O from traz o telefone ou o BSUID — a API aceita os dois.

Claude Code

claude mcp add --transport http connectawhats https://connecta-api.riapp.app/mcp \
  --header "Authorization: Bearer cwk_SUA_CHAVE"

# conferir
claude mcp list

Claude Desktop

Os conectores personalizados do Claude (claude.ai e Desktop) usam OAuth, que este servidor não oferece. Use a pontemcp-remote (precisa de Node.js) em claude_desktop_config.json (Configurações → Desenvolvedor → Editar config):

{
  "mcpServers": {
    "connectawhats": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://connecta-api.riapp.app/mcp", "--header", "Authorization:${AUTH}"],
      "env": { "AUTH": "Bearer cwk_SUA_CHAVE" }
    }
  }
}

Reinicie o Claude Desktop. As ferramentas aparecem no ícone de ferramentas da conversa.

Cursor

{
  "mcpServers": {
    "connectawhats": {
      "url": "https://connecta-api.riapp.app/mcp",
      "headers": { "Authorization": "Bearer cwk_SUA_CHAVE" }
    }
  }
}

VS Code (GitHub Copilot)

{
  "inputs": [
    { "id": "cwk", "type": "promptString", "description": "Chave de API do ConnectaWhats", "password": true }
  ],
  "servers": {
    "connectawhats": {
      "type": "http",
      "url": "https://connecta-api.riapp.app/mcp",
      "headers": { "Authorization": "Bearer ${input:cwk}" }
    }
  }
}

API da Anthropic (Claude)

O conector MCP da Messages API chama o servidor direto da nuvem da Anthropic. Precisa das duas partes: mcp_servers e o mcp_toolset em tools.

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: mcp-client-2025-11-20" \
  -H "content-type: application/json" \
  -d '{
    "model": "claude-opus-5-5",
    "max_tokens": 4000,
    "mcp_servers": [{
      "type": "url",
      "url": "https://connecta-api.riapp.app/mcp",
      "name": "connectawhats",
      "authorization_token": "cwk_SUA_CHAVE"
    }],
    "tools": [{ "type": "mcp_toolset", "mcp_server_name": "connectawhats" }],
    "messages": [{ "role": "user", "content": "Quantas mensagens cada tenant recebeu nos últimos 7 dias e qual teve mais falhas?" }]
  }'

O authorization_token é enviado como Authorization: Bearer, então vai só a chave, sem o prefixo “Bearer”.

API da OpenAI (Responses)

"tools": [{
  "type": "mcp",
  "server_label": "connectawhats",
  "server_url": "https://connecta-api.riapp.app/mcp",
  "headers": { "Authorization": "Bearer cwk_SUA_CHAVE" },
  "require_approval": "never",
  "allowed_tools": ["get_metrics_overview", "get_metrics_errors", "get_contact_metrics"]
}]

Com ferramentas de envio liberadas, prefira require_approval ligado para revisar antes de mandar mensagem a clientes.

Testar na mão (curl)

Útil para conferir a chave e a URL. O header Accept precisa aceitar JSON e SSE:

curl -X POST https://connecta-api.riapp.app/mcp \
  -H "Authorization: Bearer cwk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

curl -X POST https://connecta-api.riapp.app/mcp \
  -H "Authorization: Bearer cwk_SUA_CHAVE" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_metrics_overview","arguments":{"period":"7d"}}}'

Perguntas que um agente conectado responde

• “Quantas mensagens cada tenant recebeu esta semana, e qual teve mais falhas?”
• “Quais os erros de envio mais comuns nos últimos 30 dias e o que significam?”
• “Em que horário o número X recebe mais mensagens?”
• “Meu webhook está falhando? Para qual destino?”
• “Quais leads de anúncio viraram quentes este mês? Resuma a conversa de cada um.”
• “Quanto gastei com templates de marketing e qual teve a melhor taxa de leitura?”