ConextBotConextBot Docs

Referência da API

Envie mensagens e templates pelo seu número oficial da Meta, baixe mídias recebidas e receba eventos em tempo real no seu servidor. A chave de API pertence a um número (agente): ela só acessa o WhatsApp conectado a esse agente.

URL base: https://app.conext.click

1. Autenticação

  1. Conecte o número em Números.
  2. Abra API e templates, escolha o número e gere uma chave (formato cxk_…).
  3. A chave completa aparece uma única vez. Guarde em local seguro.

Envie a chave no cabeçalho em todas as chamadas:

Authorization: Bearer cxk_sua_chave_aqui

Também é aceito ?api_key=… na URL, mas evite: a chave pode ficar registrada em logs.

2. Mensagens

POST/api/v1/messages

Enviar mensagem

O corpo segue o formato da Cloud API da Meta; o Conext só acrescenta messaging_product e usa o número da chave. O campo to é obrigatório (com DDI, só dígitos).

Texto livre só pode ser enviado dentro da janela de 24h depois da última mensagem do cliente. Fora dela, use um template aprovado.

curl -X POST https://app.conext.click/api/v1/messages \
  -H "Authorization: Bearer cxk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "5511999999999",
    "type": "text",
    "text": { "body": "Seu pedido saiu para entrega!" }
  }'

Template (com variáveis):

{
  "to": "5511999999999",
  "type": "template",
  "template": {
    "name": "pedido_confirmado",
    "language": { "code": "pt_BR" },
    "components": [
      { "type": "body", "parameters": [
        { "type": "text", "text": "Maria" },
        { "type": "text", "text": "#1042" }
      ] }
    ]
  }
}

Resposta de sucesso:

{ "success": true, "messages": [{ "id": "wamid.HBg..." }], "contacts": [{ "input": "5511999999999", "wa_id": "5511999999999" }] }

Erros: 401 chave inválida ou inativa · 400 número sem WhatsApp conectado, JSON inválido ou to ausente · demais códigos repassam o erro da Meta em details.

GET/api/v1/media/:id

Baixar mídia recebida

Quando o cliente envia imagem, áudio, documento ou vídeo, o webhook traz um id de mídia. Use este endpoint para baixar o arquivo: o Conext resolve a URL temporária na Meta e devolve o binário com o Content-Type correto (limite de 25 MB, sem cache).

curl -H "Authorization: Bearer cxk_sua_chave" \
  https://app.conext.click/api/v1/media/1234567890123456 -o arquivo

3. Templates

Necessários para iniciar conversas fora da janela de 24h. Também podem ser criados pelo painel, em API e templates.

GET/api/v1/templates

Listar templates

curl -H "Authorization: Bearer cxk_sua_chave" https://app.conext.click/api/v1/templates

Retorna { "templates": [{ "id", "name", "status", "category", "language", "components" }] }. Status: APPROVED, PENDING, REJECTED, PAUSED.

POST/api/v1/templates

Criar template (envia para aprovação da Meta)

Campos obrigatórios: name (minúsculas, números e _), category (UTILITY, MARKETING ou AUTHENTICATION), language e components. A análise leva de algumas horas a 72h, e a Meta pode reclassificar a categoria.

curl -X POST https://app.conext.click/api/v1/templates \
  -H "Authorization: Bearer cxk_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "pedido_confirmado",
    "category": "UTILITY",
    "language": "pt_BR",
    "components": [
      { "type": "BODY",
        "text": "Olá {{1}}, seu pedido {{2}} foi confirmado.",
        "example": { "body_text": [["Maria", "#1042"]] } }
    ]
  }'

Resposta: 201 com { "success": true, "id": "…", "status": "PENDING" }.

DELETE/api/v1/templates?name=NOME

Excluir template

Remove o template pelo nome (todas as línguas). Não pode ser desfeito.

4. Webhooks (eventos para o seu servidor)

Cadastre uma URL de webhook na chave (em API e templates). Toda notificação que a Meta enviar para o seu número (mensagens recebidas, status de entrega, leitura) é repassada para essa URL por POST, com o payload original da Meta.

Se você definiu um segredo, cada chamada traz o cabeçalho X-Conext-Signature: sha256=<hmac>, que é o HMAC-SHA256 (hex) do corpo bruto usando o segredo. Valide antes de processar:

import crypto from "crypto";

function assinaturaValida(rawBody, header, segredo) {
  const esperado = "sha256=" + crypto.createHmac("sha256", segredo).update(rawBody).digest("hex");
  const a = Buffer.from(esperado), b = Buffer.from(header || "");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

Exemplo de mensagem recebida (resumo):

{
  "object": "whatsapp_business_account",
  "entry": [{ "changes": [{ "field": "messages", "value": {
    "metadata": { "phone_number_id": "1301817689688572" },
    "contacts": [{ "profile": { "name": "Maria" }, "wa_id": "5511999999999" }],
    "messages": [{ "id": "wamid...", "from": "5511999999999", "type": "text", "text": { "body": "Oi" } }]
  } }] }]
}

Responda 2xx rápido e processe em segundo plano. O Conext não reenvia a notificação se a sua URL falhar.

5. Chat do site (webchat)

POST/api/v1/webchat

Conversar com o agente de IA pelo site

Não usa chave. Envie o botId do agente, a message e, opcionalmente, um sessionId para manter o histórico. Parâmetros utm_* e de anúncio são aceitos para atribuição. Histórico: GET /api/v1/webchat/history.

curl -X POST https://app.conext.click/api/v1/webchat \
  -H "Content-Type: application/json" \
  -d '{ "botId": "ID_DO_AGENTE", "message": "Olá", "sessionId": "visitante-123" }'

6. Gerenciar chaves por API

As chaves também podem ser listadas, criadas, alteradas e revogadas em /api/v1/keys?botId=…, mas essas chamadas usam a sessão do painel (login), não a chave de API. Para automatizar, use o painel.

Custos e limites da Meta

As mensagens são cobradas pela Meta na conta do WhatsApp Business do cliente. Pendência de pagamento bloqueia o envio (erro 131042): o painel avisa e o número para de enviar até regularizar. Limites diários e qualidade do número aparecem em Números.