Combot es el WhatsApp y el Teléfono con IA de tu empresa. La API solo necesita la clave de API: con ella tu sistema envía mensajes (texto, PDF, botones para copiar PIX y boleto) y, si quieres, recibe las respuestas y atiende el teléfono.
Disponible en el plan Bot con IA. Genera tu clave en Integraciones.
Visión general
La API es REST sobre HTTPS y usa JSON. La URL base es:
https://combot.com.br/api/v1api.combot.com.br y app.combot.com.br no existen — usa exactamente la dirección de arriba.
Primero: ¿qué va a hacer tu sistema?
Solo enviar mensajes (código de acceso, aviso, cobro, recordatorio) — el caso más común.Necesita: solo la clave de API y POST /api/v1/messages. No configures webhook.
Recibir lo que el cliente escribe y responder por tu sistema (ERP, CRM, proveedor).Necesita: la clave de API y una dirección https en tu sistema. Al guardar la clave, tu sistema llama a PUT /api/v1/integration una vez — nadie copia URL ni marca nada en el panel de Combot.
Atender el Teléfono con IA con los datos de tu sistema (proveedor de internet, TV por suscripción, banco, cualquier ERP) — como la integración lista con el SGP.Necesita: el caso 2 con phoneAi: true. Consulta Teléfono por tu sistema.
No tienes sistema: usa la IA entrenable de Combot en el panel, o pídele una respuesta en POST /api/v1/ai/reply.
Para agentes de IA
La API está hecha para integraciones — incluso por agentes de IA. Hay una descripción machine-readable lista para consumo automático:
/llms.txt — resumen del servicio y endpoints en texto, en el formato llms.txt.
/openapi.json — especificación OpenAPI 3.1 (impórtala en herramientas de IA y SDKs).
Basta apuntar tu agente al OpenAPI y usar la clave de API de la empresa como Bearer token. En la pantalla del sistema que integre, pide solo la clave de API — nada de campo “secreto del webhook”.
Autenticación
Todas las llamadas usan tu clave de API en el header Authorization. Genera y rota la clave en Integraciones.
Authorization: Bearer cb_live_sua_chave_aquiMantén la clave en el backend. Nunca la expongas en el navegador o en apps públicas.
Reglas que no cambian
Valen para cualquier sistema, ERP o IA:
La única credencial es la clave de API. No existe secreto de webhook, whsec_, token de app ni contraseña.
El webhook no es obligatorio: solo existe para quien recibe (casos 2 y 3), y tu sistema lo configura solo por la API.
Para responder a un mensaje que llegó por el webhook, usa el conversationId que vino en él — no el teléfono.
Para comenzar una conversación (cobro, aviso), usa to con el teléfono en cualquier formato: con o sin 55, con o sin el 9º dígito, con puntuación. Combot encuentra la cuenta de WhatsApp real y usa la conversación que ya exista con el cliente.
Siempre revisa ok en la respuesta. ok: false quiere decir que el mensaje no llegó, y error dice el motivo (ej.: numero_sem_whatsapp).
En el webhook, responde 200 en hasta 8 segundos y procesa después; usa message.id para no responder dos veces.
Enviar mensaje de WhatsApp
Envía un mensaje de texto por el número de WhatsApp conectado de tu empresa.
El to acepta el teléfono en cualquier formato — (38) 99999-0000, 38999990000, +55 38 9999-0000. WhatsApp guarda parte de los celulares sin el 9º dígito; Combot descubre la forma correcta solo.
Cuerpo — por teléfono:
{
"to": "5511999998888",
"text": "Olá! Recebemos seu pedido e já estamos preparando."
}O respondiendo una conversación existente:
{
"conversationId": "clx123...",
"text": "Seu protocolo é #4821."
}Botones para copiar (PIX, boleto) — opcional:
Envía hasta 3 botones en buttons. Cada uno copia un código con un toque. Combot también envía el código en un mensaje propio, dentro de un bloque de código — esto es importante porque un código suelto (el PIX contiene br.gov.bcb.pix) se convierte en enlace en WhatsApp y el cliente termina copiando solo un fragmento.
{
"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 del botón (hasta 25 caracteres). copyCode = lo que va al portapapeles. footer es opcional. Si el dispositivo del cliente no muestra el botón, el código igual llega en el mensaje siguiente.
Archivo (PDF del boleto) e imagen (QR Code del PIX):
Informa type + url (URL pública en https — Combot descarga el archivo para enviarlo; dirección interna o de red privada es rechazada). Con multimedia, el campo text deja de ser obligatorio: la leyenda va en caption. El documento llega como una tarjeta con el nombre del archivo y botón de descargar.
{
"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"
}Ejemplo (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á!"}'Respuesta:
{
"ok": true,
"simulated": false,
"messageId": "clx456...",
"conversationId": "clx123..."
}Cuando no llega al cliente (HTTP 200, pero ok: false):
{
"ok": false,
"error": "numero_sem_whatsapp",
"messageId": "clx456...",
"conversationId": "clx123..."
}Generar respuesta de la IA
Genera una respuesta usando el agente de IA y la base de conocimiento entrenada de tu empresa. No envía nada al cliente — solo devuelve el texto.
Cuerpo:
{ "message": "vocês entregam em Curitiba?" }Respuesta:
{
"reply": "Sim! Entregamos em Curitiba em até 3 dias úteis.",
"handoff": false,
"tokensIn": 812,
"tokensOut": 34
}handoff: true indica que la IA sugiere transferir a un atendente humano.
Configurar recepción (tu sistema llama solo)
Dice a Combot a dónde entregar lo que tu sistema recibe. Llámalo cuando el usuario guarde la clave en tu sistema. Envía solo lo que quieres cambiar. GET /api/v1/integration muestra cómo está.
{
"webhookUrl": "https://seu-sistema.com/webhooks/combot",
"forwardInbound": true,
"phoneAi": false
}webhookUrl: https en un dominio público, sin puerto. null desactiva la recepción.
forwardInbound: true = los mensajes van a tu sistema y la IA de Combot no responde.
phoneAi: true = el Teléfono con IA usa el entrenamiento y las herramientas de tu sistema.
Respuesta:
{ "ok": true, "webhookUrl": "https://seu-sistema.com/webhooks/combot", "forwardInbound": true, "phoneAi": false }Recibir mensajes (caso 2)
Solo para el caso 2. Después del PUT /api/v1/integration con forwardInbound: true, cada mensaje recibido se envía por POST a su dirección, y la IA de Combot se queda callada (quien responde es su sistema):
Cuerpo enviado a su 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 al cliente llamando a POST /api/v1/messages con el conversationId recibido. Devuelva 200 rápidamente — el procesamiento pesado debe ser asíncrono de su lado.
Deduplicación: use message.id (id estable de Combot) o message.externalId (el wamid de WhatsApp) como clave idempotente — Meta puede reentregar el mismo evento.
Teléfono con IA por su sistema (caso 3)
La llamada es atendida por la IA de voz de Combot en el número de la empresa — idioma, voz y minutos siguen siendo de Combot —, pero lo que sabe y lo que hace proviene de su sistema. Ejemplo: la persona llama, dice el CPF, la IA consulta su sistema (“su plan es el Fibra 300, al día”) y envía la 2ª vía por WhatsApp. Llame con phoneAi: true en el PUT /api/v1/integration (o el propietario elige en Teléfono con IA → Quién atiende → Mi sistema).
Durante la llamada, Combot hace POST a su dirección (la misma del caso 2), separando por el campo event:
El idioma y la voz se eligen en la página de cada número, incluso cuando el ERP atiende. El ERP recibe idioma y voz y debe responder con información compatible. La voz de Combot sigue el idioma seleccionado; no depende del idioma usado en el panel.
Para validar la conexión sin hacer una llamada, implemente el evento integration.test: verifique la firma normalmente y responda {"ok":true}, sin crear pedidos, tickets ni mensajes. El botón Probar conexión en la pantalla de Integraciones envía ese evento firmado y espera hasta 6 segundos.
1. call.started — responda en hasta 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": [] }
]
}Sin respuesta a tiempo, ok: false o HTTP 409: la llamada informa que el ERP está no disponible y finaliza con cortesía. No usa otro entrenamiento, agenda, producto o servicio de Combot.
2. call.tool — la IA pidió una herramienta; responda en hasta 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 devuelva código PIX o de barras para que la IA lo dicte: envíelo por WhatsApp con POST /api/v1/messages (to = el número de) y devuelva “enviado por WhatsApp”. ¿Algo lento? Responda primero y hágalo después.
3. call.ended — para su historial
{ "event": "call.ended", "ligacaoId": "clx...", "de": "31999990000",
"duracaoSeg": 140, "resumo": "...", "transcricao": "..." }Firma (opcional)
Toda llamada de Combot a su sistema (mensajes y teléfono) lleva el header X-Combot-Signature: HMAC-SHA256 del cuerpo crudo, hecho con su clave de API — la misma del Authorization. No existe otro secreto. Verificarlo es opcional, pero 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));
}Errores
La API usa códigos HTTP convencionales y un cuerpo { "error": "..." }:
401 missing_token / invalid_token — clave ausente o inválida.
402 billing_blocked — la cuenta está bloqueada por mensualidad en atraso. Pague en Financiero y la API vuelve.
403 plan_without_api_access — el plan de la empresa no habilita la API.
403 account_inactive — la cuenta fue cerrada o bloqueada.
400 missing_text / missing_recipient / missing_message — cuerpo incompleto.
400 invalid_webhook_url / webhook_url_required — dirección inválida o faltante en el PUT /api/v1/integration.
429 ai_monthly_limit_reached — la IA del mes llegó al límite del plan (POST /api/v1/ai/reply); vuelve el mes siguiente.
403 plan_without_ai — el plan no incluye IA.
429 rate_limit_exceeded — espere el tiempo del encabezado Retry-After y vuelva a intentarlo.
404 conversation_not_found — conversación inexistente para la empresa.
409 no_whatsapp_channel — ningún WhatsApp conectado en la empresa.
200 con ok: false — el mensaje se registró, pero no llegó al cliente; error indica el motivo.
Cuando algo no funciona
Ubique en qué punto se detuvo el mensaje, en este orden:
El mensaje del cliente no llega a su sistema. Llame a GET /api/v1/integration: el webhookUrl debe ser su dirección, en https, y forwardInbound debe estar en true. Verifique también si el WhatsApp de la empresa está Conectado en Canales.
Llega, pero su sistema lo rechaza. Si verifica la firma, use el cuerpo crudo (antes de convertir el JSON) y la clave de API; responda 200 en hasta 8 segundos — procese después.
Su sistema responde, pero el cliente no recibe. Lea el ok y el error de la respuesta de POST /api/v1/messages: numero_sem_whatsapp quiere decir que ese teléfono no tiene WhatsApp; los errores que empiezan con evolution_ casi siempre son el celular de la empresa desconectado — lea el código QR de nuevo.
Responde doble. Use message.id como clave: el mismo evento puede llegar más de una vez.
¿Listo para integrar?
Genere su clave de API en Integraciones — es lo único que su sistema necesita.