Combot est le WhatsApp et le Téléphone avec IA de votre entreprise. L'API n'a besoin que de la clé d'API : avec elle, votre système envoie des messages (texte, PDF, boutons pour copier PIX et boleto) et, si vous le souhaitez, reçoit les réponses et prend en charge le téléphone.
Disponible dans le forfait Bot avec IA. Générez votre clé dans Intégrations.
Vue d'ensemble
L'API est REST sur HTTPS et utilise JSON. L'URL de base est :
https://combot.com.br/api/v1api.combot.com.br et app.combot.com.br n'existent pas — utilisez exactement l'adresse ci-dessus.
D'abord : que va faire votre système ?
Seulement envoyer des messages (code d'accès, avis, facturation, rappel) — le cas le plus courant.Nécessite : uniquement la clé d'API et POST /api/v1/messages. Ne configurez pas de webhook.
Recevoir ce que le client écrit et répondre via votre système (ERP, CRM, fournisseur).Nécessite : la clé d'API et une adresse https dans votre système. À l'enregistrement de la clé, votre système appelle PUT /api/v1/integration une fois — personne ne copie d'URL ni ne coche quoi que ce soit dans le panneau de Combot.
Prendre en charge le Téléphone avec IA avec les données de votre système (fournisseur d'accès internet, TV par abonnement, banque, n'importe quel ERP) — comme l'intégration prête avec le SGP.Nécessite : le cas 2 avec phoneAi: true. Voir Téléphone via votre système.
Vous n'avez pas de système : utilisez l'IA entraînable de Combot dans le panneau, ou demandez-lui une réponse via POST /api/v1/ai/reply.
Pour les agents d'IA
L'API est conçue pour les intégrations — y compris par des agents d'IA. Une description machine-readable est prête pour une consommation automatique :
/llms.txt — résumé du service et des endpoints en texte, au format llms.txt.
/openapi.json — spécification OpenAPI 3.1 (importez dans des outils d'IA et des SDK).
Il suffit de pointer votre agent vers l'OpenAPI et d'utiliser la clé d'API de l'entreprise comme Bearer token. Sur l'écran du système qu'il intègre, demandez uniquement la clé d'API — pas de champ « secret du webhook ».
Authentification
Tous les appels utilisent votre clé d'API dans le header Authorization. Générez et faites tourner la clé dans Intégrations.
Authorization: Bearer cb_live_sua_chave_aquiGardez la clé dans le backend. Ne l'exposez jamais dans le navigateur ou dans des apps publiques.
Règles qui ne changent pas
Valables pour n'importe quel système, ERP ou IA :
Le seul identifiant est la clé d'API. Il n'existe pas de secret de webhook, de whsec_, de token d'app ni de mot de passe.
Le webhook n'est pas obligatoire : il n'existe que pour ceux qui reçoivent (cas 2 et 3), et votre système le configure tout seul via l'API.
Pour répondre à un message arrivé par le webhook, utilisez le conversationId qu'il contient — pas le téléphone.
Pour commencer une conversation (facturation, avis), utilisez to avec le téléphone dans n'importe quel format : avec ou sans 55, avec ou sans le 9e chiffre, avec ponctuation. Combot trouve le vrai compte WhatsApp et utilise la conversation qui existe déjà avec le client.
Vérifiez toujours ok dans la réponse. ok: false signifie que le message n'est pas arrivé, et error en indique la raison (ex. : numero_sem_whatsapp).
Dans le webhook, répondez 200 en 8 secondes maximum et traitez ensuite ; utilisez message.id pour ne pas répondre deux fois.
Envoyer un message WhatsApp
Envoie un message texte via le numéro WhatsApp connecté de votre entreprise.
Le to accepte le téléphone dans n'importe quel format — (38) 99999-0000, 38999990000, +55 38 9999-0000. WhatsApp conserve certains cellulaires sans le 9e chiffre ; Combot trouve la bonne forme tout seul.
Corps — par téléphone :
{
"to": "5511999998888",
"text": "Olá! Recebemos seu pedido e já estamos preparando."
}Ou en répondant à une conversation existante :
{
"conversationId": "clx123...",
"text": "Seu protocolo é #4821."
}Boutons pour copier (PIX, boleto) — facultatif :
Envoyez jusqu'à 3 boutons dans buttons. Chacun copie un code en un toucher. Combot envoie aussi le code dans un message à part, dans un bloc de code — c'est important car un code isolé (le PIX contient br.gov.bcb.pix) devient un lien dans WhatsApp et le client finit par ne copier qu'un fragment.
{
"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 = texte du bouton (25 caractères maximum). copyCode = ce qui va dans le presse-papiers. footer est facultatif. Si l'appareil du client n'affiche pas le bouton, le code arrive quand même dans le message suivant.
Fichier (PDF du boleto) et image (QR Code du PIX) :
Indiquez type + url (URL publique en https — Combot télécharge le fichier pour l'envoyer ; une adresse interne ou de réseau privé est refusée). Avec un média, le champ text n'est plus obligatoire : la légende va dans caption. Le document arrive sous forme de carte avec le nom du fichier et un bouton de téléchargement.
{
"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"
}Exemple (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á!"}'Réponse :
{
"ok": true,
"simulated": false,
"messageId": "clx456...",
"conversationId": "clx123..."
}Quand le message n'arrive pas au client (HTTP 200, mais ok: false) :
{
"ok": false,
"error": "numero_sem_whatsapp",
"messageId": "clx456...",
"conversationId": "clx123..."
}Générer une réponse de l'IA
Génère une réponse en utilisant l'agent d'IA et la base de connaissances entraînée de votre entreprise. N'envoie rien au client — renvoie seulement le texte.
Corps :
{ "message": "vocês entregam em Curitiba?" }Réponse :
{
"reply": "Sim! Entregamos em Curitiba em até 3 dias úteis.",
"handoff": false,
"tokensIn": 812,
"tokensOut": 34
}handoff: true indique que l'IA suggère de transférer à un agent humain.
Configurer la réception (votre système l'appelle tout seul)
Indique à Combot où livrer ce que votre système reçoit. Appelez-le quand l'utilisateur enregistre la clé dans votre système. N'envoyez que ce que vous voulez modifier. GET /api/v1/integration montre l'état actuel.
{
"webhookUrl": "https://seu-sistema.com/webhooks/combot",
"forwardInbound": true,
"phoneAi": false
}webhookUrl : https sur un domaine public, sans port. null désactive la réception.
forwardInbound: true = les messages vont vers votre système et l'IA de Combot ne répond pas.
phoneAi: true = le Téléphone avec IA utilise l'entraînement et les outils de votre système.
Réponse :
{ "ok": true, "webhookUrl": "https://seu-sistema.com/webhooks/combot", "forwardInbound": true, "phoneAi": false }Recevoir des messages (cas 2)
Uniquement pour le cas 2. Après le PUT /api/v1/integration avec forwardInbound: true, chaque message reçu est envoyé par POST à votre adresse, et l'IA de Combot reste silencieuse (c'est votre système qui répond) :
Corps envoyé à votre système :
{
"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
}Répondez au client en appelant POST /api/v1/messages avec le conversationId reçu. Renvoyez 200 rapidement — le traitement lourd doit être asynchrone de votre côté.
Déduplication : utilisez message.id (id stable de Combot) ou message.externalId (le wamid de WhatsApp) comme clé idempotente — Meta peut relivrer le même événement.
Téléphone avec IA via votre système (cas 3)
L'appel est pris en charge par l'IA vocale de Combot sur le numéro de l'entreprise — la langue, la voix et les minutes restent celles de Combot —, mais ce qu'elle sait et ce qu'elle fait provient de votre système. Exemple : la personne appelle, énonce son CPF, l'IA consulte votre système (« votre offre est Fibra 300, à jour ») et envoie la 2e copie sur WhatsApp. Appelez avec phoneAi: true dans le PUT /api/v1/integration (ou le propriétaire choisit dans Téléphone avec IA → Qui répond → Mon système).
Pendant l'appel, Combot fait un POST à votre adresse (la même que dans le cas 2), en distinguant par le champ event :
La langue et la voix sont choisies sur la page de chaque numéro, y compris lorsque l'ERP répond. L'ERP reçoit la langue et la voix et doit répondre avec des informations compatibles. La voix de Combot suit la langue sélectionnée ; elle ne dépend pas de la langue utilisée dans le panneau.
Pour valider la connexion sans passer d'appel, implémentez l'événement integration.test : vérifiez la signature normalement et répondez {"ok":true}, sans créer de commandes, de tickets ou de messages. Le bouton Tester la connexion sur l'écran Intégrations envoie cet événement signé et attend jusqu'à 6 secondes.
1. call.started — répondez sous 6 secondes
// 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": [] }
]
}Sans réponse à temps, ok: false ou HTTP 409 : l'appel indique que l'ERP est indisponible et se termine poliment. Il n'utilise pas un autre entraînement, agenda, produit ou service de Combot.
2. call.tool — l'IA a demandé un outil ; répondez sous 20 secondes
// 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." }Ne renvoyez jamais de code PIX ou de code-barres à l'IA pour qu'elle le dicte : envoyez-le par WhatsApp avec POST /api/v1/messages (to = le numéro de) et renvoyez « envoyé sur WhatsApp ». Quelque chose de lent ? Répondez d'abord et faites ensuite.
3. call.ended — pour votre historique
{ "event": "call.ended", "ligacaoId": "clx...", "de": "31999990000",
"duracaoSeg": 140, "resumo": "...", "transcricao": "..." }Signature (facultative)
Chaque appel de Combot à votre système (messages et téléphone) porte l'en-tête X-Combot-Signature : HMAC-SHA256 du corps brut, calculé avec votre clé d'API — la même que celle de l'Authorization. Il n'existe aucun autre secret. La vérification est facultative, mais recommandée :
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));
}Erreurs
L'API utilise des codes HTTP conventionnels et un corps { "error": "..." } :
401 missing_token / invalid_token — clé absente ou invalide.
402 billing_blocked — le compte est bloqué pour mensualité en retard. Payez dans Financeiro et l'API refonctionne.
403 plan_without_api_access — le forfait de l'entreprise ne donne pas accès à l'API.
403 account_inactive — le compte a été fermé ou bloqué.
400 missing_text / missing_recipient / missing_message — corps incomplet.
400 invalid_webhook_url / webhook_url_required — adresse invalide ou manquante dans le PUT /api/v1/integration.
429 ai_monthly_limit_reached — l'IA du mois a atteint la limite du forfait (POST /api/v1/ai/reply) ; elle revient le mois suivant.
403 plan_without_ai — le forfait n'inclut pas l'IA.
429 rate_limit_exceeded — attendez la durée indiquée par l'en-tête Retry-After et réessayez.
404 conversation_not_found — conversation inexistante pour l'entreprise.
409 no_whatsapp_channel — aucun WhatsApp connecté dans l'entreprise.
200 avec ok: false — le message a été enregistré, mais n'est pas arrivé au client ; error en indique la raison.
Quand quelque chose ne fonctionne pas
Repérez où le message s'est arrêté, dans cet ordre :
Le message du client n'arrive pas dans votre système. Appelez GET /api/v1/integration : le webhookUrl doit être votre adresse, en https, et forwardInbound doit être true. Vérifiez aussi que le WhatsApp de l'entreprise est Connecté dans Canais.
Il arrive, mais votre système le refuse. Si vous vérifiez la signature, utilisez le corps brut (avant de convertir le JSON) et la clé d'API ; répondez 200 sous 8 secondes — traitez ensuite.
Votre système répond, mais le client ne reçoit rien. Lisez le ok et l'error de la réponse de POST /api/v1/messages : numero_sem_whatsapp signifie que ce téléphone n'a pas WhatsApp ; les erreurs commençant par evolution_ correspondent presque toujours au téléphone de l'entreprise déconnecté — relisez le QR Code.
Il répond en double. Utilisez message.id comme clé : le même événement peut arriver plus d'une fois.
Prêt à intégrer ?
Générez votre clé d'API dans Integrações — c'est la seule chose dont votre système a besoin.