API do Combot

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

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

api.combot.com.br e app.combot.com.br não existem — use exatamente o endereço acima.

1. Só enviar mensagens (código de acesso, aviso, cobrança, lembrete) — o caso mais comum.
   Precisa: só a chave de API e POST /api/v1/messages. Não configure webhook.
2. Receber o que o cliente escreve e responder pelo seu sistema (ERP, CRM, provedor).
   Precisa: a chave de API e um endereço https no seu sistema. Ao salvar a chave, o seu sistema chama PUT /api/v1/integration uma vez — ninguém copia URL nem marca nada no painel do Combot.
3. Atender o Telefone com IA com os dados do seu sistema (provedor de internet, TV por assinatura, banco, qualquer ERP) — como a integração pronta com o SGP.
   Precisa: o caso 2 com phoneAi: true. Veja Telefone pelo seu sistema.
4. Não tem sistema: use a IA treinável do Combot no painel, ou peça uma resposta a ela em POST /api/v1/ai/reply.

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. Na tela do sistema que ele integrar, peça só a chave de API — nada de campo “segredo do webhook”.

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.

Valem para qualquer sistema, ERP ou IA:

1. A única credencial é a chave de API. Não existe segredo de webhook, whsec_, token de app ou senha.
2. Webhook não é obrigatório: só existe para quem recebe (casos 2 e 3), e o seu sistema o configura sozinho pela API.
3. Para responder a uma mensagem que chegou pelo webhook, use o conversationId que veio nele — não o telefone.
4. Para começar uma conversa (cobrança, aviso), use to com o telefone em qualquer formato: com ou sem 55, com ou sem o 9º dígito, com pontuação. O Combot acha a conta de WhatsApp de verdade e usa a conversa que já existir com o cliente.
5. Sempre confira ok na resposta. ok: false quer dizer que a mensagem não chegou, e error diz o motivo (ex.: numero_sem_whatsapp).
6. No webhook, responda 200 em até 8 segundos e processe depois; use message.id para não responder duas vezes.

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

O to aceita o telefone em qualquer formato — (38) 99999-0000, 38999990000, +55 38 9999-0000. O WhatsApp guarda parte dos celulares sem o 9º dígito; o Combot descobre a forma certa sozinho.

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 em https — o Combot baixa o arquivo para enviar; endereço interno ou de rede privada é recusado). 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..."
}

Quando não chega ao cliente (HTTP 200, mas ok: false):

{
  "ok": false,
  "error": "numero_sem_whatsapp",
  "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.

Diz ao Combot para onde entregar o que o seu sistema recebe. Chame quando o usuário salvar a chave no seu sistema. Mande só o que quer mudar. GET /api/v1/integration mostra como está.

{
  "webhookUrl": "https://seu-sistema.com/webhooks/combot",
  "forwardInbound": true,
  "phoneAi": false
}

• webhookUrl: https num domínio público, sem porta. null desliga o recebimento.
• forwardInbound: true = as mensagens vão para o seu sistema e a IA do Combot não responde.
• phoneAi: true = o Telefone com IA usa o treinamento e as ferramentas do seu sistema.

Resposta:

{ "ok": true, "webhookUrl": "https://seu-sistema.com/webhooks/combot", "forwardInbound": true, "phoneAi": false }

Só para o caso 2. Depois do PUT /api/v1/integration com forwardInbound: true, cada mensagem recebida é enviada por POST para o seu endereço, e a IA do Combot fica calada (quem responde é o seu sistema):

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.

A ligação é atendida pela IA de voz do Combot no número da empresa — idioma, voz e minutos continuam do Combot —, mas o que ela sabe e o que ela faz vem do seu sistema. Exemplo: a pessoa liga, fala o CPF, a IA consulta o seu sistema (“seu plano é o Fibra 300, em dia”) e manda a 2ª via no WhatsApp. Ligue com phoneAi: true no PUT /api/v1/integration (ou o dono escolhe em Telefone com IA → Quem atende → Meu sistema).

Durante a ligação o Combot faz POST no seu endereço (o mesmo do caso 2), separando pelo campo event:

O idioma e a voz são escolhidos na página de cada número, inclusive quando o ERP atende. O ERP recebe idioma e voz e deve responder com informações compatíveis. A voz do Combot segue o idioma selecionado; ele não depende da língua usada no painel.

Para validar a conexão sem fazer uma ligação, implemente o evento integration.test: verifique a assinatura normalmente e responda {"ok":true}, sem criar pedidos, chamados ou mensagens. O botão Testar conexão na tela de Integrações envia esse evento assinado e aguarda até 6 segundos.

1. call.started — responda em até 6 segundos

// recebe
{ "event": "call.started", "evento": "ligacao.inicio", "ligacaoId": "clx...", "de": "31999990000", "para": "553130309999", "idioma": "en-US", "voz": "ana" }

// devolve
{
  "ok": true,
  "saudacao": "Empresa Exemplo, olá! Aqui é a Ana. Em que posso ajudar?",
  "instrucoes": "Você é a Ana, da Empresa Exemplo... (o treinamento e, se 'de' for cliente, os dados dele)",
  "ferramentas": [
    {
      "nome": "consultar_assinatura",
      "descricao": "Acha o cliente pelo CPF e diz o plano e se está em dia.",
      "parametros": [{ "nome": "cpf_cnpj", "tipo": "string", "descricao": "Só números", "obrigatorio": true }]
    },
    { "nome": "enviar_segunda_via", "descricao": "Manda a fatura com PIX no WhatsApp de quem liga.", "parametros": [] }
  ]
}

Sem resposta a tempo, ok: false ou HTTP 409: a ligação informa que o ERP está indisponível e encerra com educação. Não usa outro treinamento, agenda, produto ou serviço do Combot.

2. call.tool — a IA pediu uma ferramenta; responda em até 20 segundos

// recebe
{ "event": "call.tool", "ligacaoId": "clx...", "de": "31999990000",
  "ferramenta": "consultar_assinatura", "argumentos": { "cpf_cnpj": "12345678909" } }

// devolve — "texto" é o que a IA vai FALAR
{ "ok": true, "texto": "Cliente Maria. Plano Fibra 300, em dia." }

Nunca devolva código PIX ou de barras para a IA ditar: envie pelo WhatsApp com POST /api/v1/messages (to = o número de) e devolva “mandei no WhatsApp”. Coisa lenta? Responda primeiro e faça depois.

3. call.ended — para o seu histórico

{ "event": "call.ended", "ligacaoId": "clx...", "de": "31999990000",
  "duracaoSeg": 140, "resumo": "...", "transcricao": "..." }

Toda chamada do Combot ao seu sistema (mensagens e telefone) leva o header X-Combot-Signature: HMAC-SHA256 do corpo cru, feito com a sua chave de API — a mesma do Authorization. Não existe outro segredo. Conferir é opcional, mas recomendado:

import crypto from "crypto";

function isValid(rawBody, signature, apiKey) {
  const expected =
    "sha256=" + crypto.createHmac("sha256", apiKey).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.
• 402 billing_blocked — a conta está bloqueada por mensalidade em atraso. Pague em Financeiro e a API volta.
• 403 plan_without_api_access — o plano da empresa não libera a API.
• 403 account_inactive — a conta foi encerrada ou bloqueada.
• 400 missing_text / missing_recipient / missing_message — corpo incompleto.
• 400 invalid_webhook_url / webhook_url_required — endereço inválido ou faltando no PUT /api/v1/integration.
• 429 ai_monthly_limit_reached — a IA do mês chegou ao limite do plano (POST /api/v1/ai/reply); volta no mês seguinte.
• 403 plan_without_ai — o plano não inclui IA.
• 429 rate_limit_exceeded — espere o tempo do cabeçalho Retry-After e tente de novo.
• 404 conversation_not_found — conversa inexistente para a empresa.
• 409 no_whatsapp_channel — nenhum WhatsApp conectado na empresa.
• 200 com ok: false — a mensagem foi registrada, mas não chegou ao cliente; error diz o motivo.

Ache em qual ponto a mensagem parou, nesta ordem:

1. A mensagem do cliente não chega no seu sistema. Chame GET /api/v1/integration: o webhookUrl tem de ser o seu endereço, em https, e forwardInbound tem de estar true. Confira também se o WhatsApp da empresa está Conectado em Canais.
2. Chega, mas o seu sistema recusa. Se confere a assinatura, use o corpo cru (antes de converter o JSON) e a chave de API; responda 200 em até 8 segundos — processe depois.
3. O seu sistema responde, mas o cliente não recebe. Leia o ok e o error da resposta de POST /api/v1/messages: numero_sem_whatsapp quer dizer que aquele telefone não tem WhatsApp; os erros que começam com evolution_ quase sempre são o celular da empresa desconectado — leia o QR Code de novo.
4. Responde em dobro. Use message.id como chave: o mesmo evento pode chegar mais de uma vez.