API do Combot

A API é REST sobre HTTPS e usa JSON. A URL base é:

https://combot.com.br/api/v1

O Combot é a sua conexão com o WhatsApp. Ele cuida de entregar e receber as mensagens — nada mais. O fluxo é sempre este:
Você manda → chega no Combot → o Combot entrega no WhatsApp do cliente.
O cliente responde → o Combot recebe → o Combot repassa para o seu sistema (webhook).

Escolha o cenário conforme você TER ou NÃO ter um sistema próprio:

• Você JÁ TEM um sistema (ERP, ISP, CRM…): o Combot é só o transporte. Ele encaminha cada mensagem recebida para o seu sistema (webhook) e o seu sistema responde chamando POST /api/v1/messages. Quem pensa e decide é o seu sistema — a IA do Combot fica desligada.
• Você NÃO TEM sistema: use a IA do Combot para responder sozinha — direto no painel, ou chamando POST /api/v1/ai/reply e usando a resposta.

A API é feita para integrações — inclusive por agentes de IA. Há uma descrição machine-readable pronta para consumo automático:

• /llms.txt — resumo do serviço e endpoints em texto, no formato llms.txt.
• /openapi.json — especificação OpenAPI 3.1 (importe em ferramentas de IA e SDKs).

Basta apontar seu agente para o OpenAPI e usar a chave de API da empresa como Bearer token.

Todas as chamadas usam sua chave de API no header Authorization. Gere e rotacione a chave em Integrações.

Authorization: Bearer cb_live_sua_chave_aqui

Mantenha a chave no backend. Nunca a exponha no navegador ou em apps públicos.

Envia uma mensagem de texto pelo número de WhatsApp conectado da sua empresa.

Corpo — por telefone:

{
  "to": "5511999998888",
  "text": "Olá! Recebemos seu pedido e já estamos preparando."
}

Ou respondendo uma conversa existente:

{
  "conversationId": "clx123...",
  "text": "Seu protocolo é #4821."
}

Botões de copiar (PIX, boleto) — opcional:

Envie até 3 botões em buttons. Cada um copia um código com um toque. O Combot também manda o código numa mensagem própria, dentro de um bloco de código — isso é importante porque um código solto (o PIX contém br.gov.bcb.pix) vira link no WhatsApp e o cliente acaba copiando só um pedaço.

{
  "to": "5511999998888",
  "text": "*PIX copia-e-cola* — R$ 119,90",
  "footer": "Fast Telekom",
  "buttons": [
    { "displayText": "📋 Copiar código Pix", "copyCode": "00020126..." },
    { "displayText": "📋 Copiar código do boleto", "copyCode": "34191.79001..." }
  ]
}

displayText = texto do botão (até 25 caracteres). copyCode = o que vai para a área de transferência. footer é opcional. Se o aparelho do cliente não exibir o botão, o código ainda chega na mensagem seguinte.

Arquivo (PDF do boleto) e imagem (QR Code do PIX):

Informe type + url (URL pública — o Combot baixa o arquivo para enviar). Com mídia, o campo text deixa de ser obrigatório: a legenda vai em caption. O documento chega como um cartão com o nome do arquivo e botão de baixar.

{
  "to": "5511999998888",
  "type": "document",
  "url": "https://exemplo.com/boleto.pdf",
  "filename": "Fatura.pdf",
  "caption": "Total: R$ 119,90"
}

{
  "to": "5511999998888",
  "type": "image",
  "url": "https://exemplo.com/qrcode-pix.png",
  "caption": "Aponte a câmera do banco e pague"
}

Exemplo (cURL):

curl -X POST https://combot.com.br/api/v1/messages \
  -H "Authorization: Bearer cb_live_sua_chave" \
  -H "Content-Type: application/json" \
  -d '{"to":"5511999998888","text":"Olá!"}'

Resposta:

{
  "ok": true,
  "simulated": false,
  "messageId": "clx456...",
  "conversationId": "clx123..."
}

Gera uma resposta usando o agente de IA e a base de conhecimento treinada da sua empresa. Não envia nada ao cliente — apenas devolve o texto.

Corpo:

{ "message": "vocês entregam em Curitiba?" }

Resposta:

{
  "reply": "Sim! Entregamos em Curitiba em até 3 dias úteis.",
  "handoff": false,
  "tokensIn": 812,
  "tokensOut": 34
}

handoff: true indica que a IA sugere transferir para um atendente humano.

Em Integrações, informe a URL do seu webhook e ative “Redirecionar atendimentos para o meu sistema”. A partir daí, cada mensagem recebida é enviada por POST para a sua URL:

Corpo enviado ao seu sistema:

{
  "event": "message.received",
  "conversationId": "clx123...",
  "contact": { "id": "clx...", "name": "Maria", "phone": "5511999998888" },
  "message": {
    "id": "clm789...",
    "externalId": "wamid.HBg...",
    "text": "quero trocar meu produto",
    "direction": "inbound"
  },
  "isNewContact": false
}

Responda ao cliente chamando POST /api/v1/messages com o conversationId recebido. Retorne 200 rapidamente — o processamento pesado deve ser assíncrono do seu lado.

Deduplicação: use message.id (id estável do Combot) ou message.externalId (o wamid do WhatsApp) como chave idempotente — a Meta pode reentregar o mesmo evento.

Cada requisição inclui o header X-Combot-Signature com um HMAC-SHA256 do corpo, usando o segredo do webhook exibido em Integrações. Valide antes de confiar no payload:

import crypto from "crypto";

function isValid(rawBody, signature, secret) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

A API usa códigos HTTP convencionais e um corpo { "error": "..." }:

• 401 missing_token / invalid_token — chave ausente ou inválida.
• 403 plan_without_api_access — o plano da empresa não libera a API.
• 400 missing_text / missing_recipient / missing_message — corpo incompleto.
• 404 conversation_not_found — conversa inexistente para a empresa.
• 409 no_whatsapp_channel — nenhum WhatsApp conectado na empresa.