Combot ist das WhatsApp und das Telefon mit KI Ihres Unternehmens. Die API benötigt nur den API-Schlüssel: Damit versendet Ihr System Nachrichten (Text, PDF, Buttons zum Kopieren von PIX und Boleto) und empfängt, wenn gewünscht, die Antworten und bedient das Telefon.
Verfügbar im Plan Bot mit KI. Erzeugen Sie Ihren Schlüssel unter Integrationen.
Übersicht
Die API ist REST über HTTPS und verwendet JSON. Die Basis-URL ist:
https://combot.com.br/api/v1api.combot.com.br und app.combot.com.br existieren nicht — verwenden Sie genau die oben genannte Adresse.
Zuerst: Was soll Ihr System tun?
Nur Nachrichten senden (Zugangscode, Hinweis, Zahlungsaufforderung, Erinnerung) — der häufigste Fall.Benötigt: nur den API-Schlüssel und POST /api/v1/messages. Keinen Webhook konfigurieren.
Empfangen, was der Kunde schreibt, und über Ihr System antworten (ERP, CRM, Anbieter).Benötigt: den API-Schlüssel und eine https-Adresse in Ihrem System. Beim Speichern des Schlüssels ruft Ihr System einmal PUT /api/v1/integration auf — niemand kopiert eine URL oder setzt etwas im Combot-Panel.
Das Telefon mit KI mit den Daten Ihres Systems bedienen (Internetprovider, Pay-TV, Bank, beliebiges ERP) — wie die fertige Integration mit dem SGP.Benötigt: Fall 2 mit phoneAi: true. Siehe Telefon über Ihr System.
Kein System vorhanden: Nutzen Sie die trainierbare KI von Combot im Panel oder fordern Sie eine Antwort von ihr über POST /api/v1/ai/reply an.
Für KI-Agenten
Die API ist für Integrationen gemacht — auch durch KI-Agenten. Es gibt eine machine-readable Beschreibung, die automatisch konsumiert werden kann:
/llms.txt — Zusammenfassung des Dienstes und der Endpunkte als Text, im Format llms.txt.
/openapi.json — OpenAPI-3.1-Spezifikation (importierbar in KI-Tools und SDKs).
Richten Sie Ihren Agenten einfach auf das OpenAPI und verwenden Sie den API-Schlüssel des Unternehmens als Bearer-Token. Auf dem Bildschirm des Systems, das er integriert, verlangen Sie nur den API-Schlüssel — kein Feld „Webhook-Geheimnis“.
Authentifizierung
Alle Aufrufe verwenden Ihren API-Schlüssel im Header Authorization. Erzeugen und rotieren Sie den Schlüssel unter Integrationen.
Authorization: Bearer cb_live_sua_chave_aquiBewahren Sie den Schlüssel im Backend auf. Geben Sie ihn niemals im Browser oder in öffentlichen Apps preis.
Regeln, die sich nicht ändern
Gelten für jedes System, ERP oder jede KI:
Die einzige Anmeldeinformation ist der API-Schlüssel. Es gibt kein Webhook-Geheimnis, kein whsec_, keinen App-Token und kein Passwort.
Der Webhook ist nicht verpflichtend: Er existiert nur für Empfänger (Fälle 2 und 3), und Ihr System konfiguriert ihn selbst über die API.
Um auf eine über den Webhook eingegangene Nachricht zu antworten, verwenden Sie die darin übermittelte conversationId — nicht die Telefonnummer.
Um ein Gespräch zu beginnen (Zahlungsaufforderung, Hinweis), verwenden Sie to mit der Telefonnummer in beliebigem Format: mit oder ohne 55, mit oder ohne 9. Ziffer, mit Satzzeichen. Combot findet das echte WhatsApp-Konto und verwendet das bereits bestehende Gespräch mit dem Kunden.
Prüfen Sie immer ok in der Antwort. ok: false bedeutet, dass die Nachricht nicht angekommen ist, und error nennt den Grund (z. B. numero_sem_whatsapp).
Antworten Sie im Webhook innerhalb von 8 Sekunden mit 200 und verarbeiten Sie danach; verwenden Sie message.id, um nicht doppelt zu antworten.
WhatsApp-Nachricht senden
Sendet eine Textnachricht über die verbundene WhatsApp-Nummer Ihres Unternehmens.
to akzeptiert die Telefonnummer in beliebigem Format — (38) 99999-0000, 38999990000, +55 38 9999-0000. WhatsApp speichert einen Teil der Mobilnummern ohne die 9. Ziffer; Combot findet die richtige Form selbst.
Body — per Telefonnummer:
{
"to": "5511999998888",
"text": "Olá! Recebemos seu pedido e já estamos preparando."
}Oder als Antwort auf ein bestehendes Gespräch:
{
"conversationId": "clx123...",
"text": "Seu protocolo é #4821."
}Buttons zum Kopieren (PIX, Boleto) — optional:
Senden Sie bis zu 3 Buttons in buttons. Jeder kopiert einen Code mit einem Tippen. Combot sendet den Code außerdem in einer eigenen Nachricht innerhalb eines Codeblocks — das ist wichtig, weil ein freistehender Code (PIX enthält br.gov.bcb.pix) in WhatsApp zum Link wird und der Kunde am Ende nur einen Teil kopiert.
{
"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 = Text des Buttons (bis zu 25 Zeichen). copyCode = was in die Zwischenablage kommt. footer ist optional. Wenn das Gerät des Kunden den Button nicht anzeigt, kommt der Code trotzdem in der folgenden Nachricht an.
Datei (Boleto-PDF) und Bild (PIX-QR-Code):
Geben Sie type + url an (öffentliche URL unter https — Combot lädt die Datei zum Senden herunter; interne oder private Netzwerkadressen werden abgelehnt). Bei Medien ist das Feld text nicht mehr verpflichtend: Die Bildunterschrift steht in caption. Das Dokument kommt als Karte mit dem Dateinamen und einer Download-Schaltfläche an.
{
"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"
}Beispiel (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á!"}'Antwort:
{
"ok": true,
"simulated": false,
"messageId": "clx456...",
"conversationId": "clx123..."
}Wenn es den Kunden nicht erreicht (HTTP 200, aber ok: false):
{
"ok": false,
"error": "numero_sem_whatsapp",
"messageId": "clx456...",
"conversationId": "clx123..."
}KI-Antwort generieren
Erzeugt eine Antwort mit dem KI-Agenten und der trainierten Wissensbasis Ihres Unternehmens. Sendet nichts an den Kunden — gibt nur den Text zurück.
Body:
{ "message": "vocês entregam em Curitiba?" }Antwort:
{
"reply": "Sim! Entregamos em Curitiba em até 3 dias úteis.",
"handoff": false,
"tokensIn": 812,
"tokensOut": 34
}handoff: true bedeutet, dass die KI vorschlägt, an einen menschlichen Mitarbeiter zu übergeben.
Empfang konfigurieren (Ihr System ruft dies selbst auf)
Teilt Combot mit, wohin geliefert werden soll, was Ihr System empfängt. Rufen Sie dies auf, wenn der Nutzer den Schlüssel in Ihrem System speichert. Senden Sie nur, was geändert werden soll. GET /api/v1/integration zeigt den aktuellen Stand.
{
"webhookUrl": "https://seu-sistema.com/webhooks/combot",
"forwardInbound": true,
"phoneAi": false
}webhookUrl: https auf einer öffentlichen Domain, ohne Port. null deaktiviert den Empfang.
forwardInbound: true = die Nachrichten gehen an Ihr System und die KI von Combot antwortet nicht.
phoneAi: true = das Telefon mit KI verwendet das Training und die Tools Ihres Systems.
Antwort:
{ "ok": true, "webhookUrl": "https://seu-sistema.com/webhooks/combot", "forwardInbound": true, "phoneAi": false }Nachrichten empfangen (Fall 2)
Nur für Fall 2. Nach dem PUT /api/v1/integration mit forwardInbound: true wird jede eingehende Nachricht per POST an Ihre Adresse gesendet, und die Combot-KI bleibt still (Ihr System antwortet):
An Ihr System gesendeter Body:
{
"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
}Antworten Sie dem Kunden durch Aufruf von POST /api/v1/messages mit der empfangenen conversationId. Geben Sie schnell 200 zurück — die aufwändige Verarbeitung sollte auf Ihrer Seite asynchron erfolgen.
Deduplizierung: Verwenden Sie message.id (stabile Combot-ID) oder message.externalId (die wamid von WhatsApp) als idempotenten Schlüssel — Meta kann dasselbe Ereignis erneut zustellen.
Telefon mit KI über Ihr System (Fall 3)
Der Anruf wird von der Combot-Sprach-KI unter der Nummer des Unternehmens entgegengenommen – Sprache, Stimme und Minuten bleiben von Combot –, aber was sie weiß und was sie tut, kommt aus Ihrem System. Beispiel: Die Person ruft an, nennt die CPF, die KI fragt Ihr System ab („Ihr Tarif ist Fibra 300, alles bezahlt“) und schickt die 2. Ausfertigung per WhatsApp. Rufen Sie mit phoneAi: true im PUT /api/v1/integration an (oder der Inhaber wählt unter Telefon mit KI → Wer nimmt ab → Mein System).
Während des Anrufs führt Combot ein POST an Ihre Adresse aus (dieselbe wie in Fall 2), unterschieden durch das Feld event:
Sprache und Stimme werden auf der Seite jeder Nummer ausgewählt, auch wenn das ERP den Anruf entgegennimmt. Das ERP erhält Sprache und Stimme und muss mit kompatiblen Informationen antworten. Die Stimme von Combot folgt der ausgewählten Sprache; sie hängt nicht von der im Panel verwendeten Sprache ab.
Um die Verbindung ohne einen Anruf zu validieren, implementieren Sie das Ereignis integration.test: Prüfen Sie die Signatur wie gewohnt und antworten Sie mit {"ok":true}, ohne Bestellungen, Tickets oder Nachrichten zu erstellen. Die Schaltfläche Verbindung testen auf dem Bildschirm Integrationen sendet dieses signierte Ereignis und wartet bis zu 6 Sekunden.
1. call.started — antworten Sie innerhalb von 6 Sekunden
// 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": [] }
]
}Ohne rechtzeitige Antwort, bei ok: false oder HTTP 409: Der Anruf teilt mit, dass das ERP nicht verfügbar ist, und beendet das Gespräch höflich. Es wird kein anderes Training, kein Kalender, kein Produkt und kein Service von Combot verwendet.
2. call.tool — die KI hat ein Tool angefordert; antworten Sie innerhalb von 20 Sekunden
// 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." }Geben Sie niemals einen PIX- oder Barcode-Code an die KI zurück, damit sie ihn vorliest: Senden Sie ihn per WhatsApp mit POST /api/v1/messages (to = die Nummer von) und geben Sie „per WhatsApp gesendet“ zurück. Etwas Langsames? Antworten Sie zuerst und tun Sie es danach.
3. call.ended — für Ihren Verlauf
{ "event": "call.ended", "ligacaoId": "clx...", "de": "31999990000",
"duracaoSeg": 140, "resumo": "...", "transcricao": "..." }Signatur (optional)
Jeder Aufruf von Combot an Ihr System (Nachrichten und Telefon) trägt den Header X-Combot-Signature: HMAC-SHA256 des Rohbodys, erstellt mit Ihrem API-Schlüssel — demselben wie im Authorization. Es gibt kein anderes Geheimnis. Die Prüfung ist optional, aber empfohlen:
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));
}Fehler
Die API verwendet übliche HTTP-Codes und einen Body { "error": "..." }:
401 missing_token / invalid_token — Schlüssel fehlt oder ist ungültig.
402 billing_blocked — das Konto ist wegen ausstehender Monatsgebühr gesperrt. Zahlen Sie unter Finanzen und die API funktioniert wieder.
403 plan_without_api_access — der Tarif des Unternehmens gibt die API nicht frei.
403 account_inactive — das Konto wurde geschlossen oder gesperrt.
400 missing_text / missing_recipient / missing_message — unvollständiger Body.
400 invalid_webhook_url / webhook_url_required — ungültige oder fehlende Adresse im PUT /api/v1/integration.
429 ai_monthly_limit_reached — die KI des Monats hat das Tariflimit erreicht (POST /api/v1/ai/reply); wieder verfügbar im nächsten Monat.
403 plan_without_ai — der Tarif enthält keine KI.
429 rate_limit_exceeded — warten Sie die Zeit im Header Retry-After ab und versuchen Sie es erneut.
404 conversation_not_found — nicht existierende Konversation für das Unternehmen.
409 no_whatsapp_channel — kein WhatsApp im Unternehmen verbunden.
200 mit ok: false — die Nachricht wurde registriert, aber nicht beim Kunden zugestellt; error nennt den Grund.
Wenn etwas nicht funktioniert
Finden Sie in dieser Reihenfolge heraus, an welcher Stelle die Nachricht hängen geblieben ist:
Die Nachricht des Kunden erreicht Ihr System nicht. Rufen Sie GET /api/v1/integration auf: webhookUrl muss Ihre Adresse in https sein und forwardInbound muss true sein. Prüfen Sie außerdem, ob das WhatsApp des Unternehmens unter Kanäle Verbunden ist.
Sie kommt an, aber Ihr System lehnt sie ab. Wenn Sie die Signatur prüfen, verwenden Sie den Rohbody (vor der JSON-Konvertierung) und den API-Schlüssel; antworten Sie innerhalb von 8 Sekunden mit 200 — verarbeiten Sie danach.
Ihr System antwortet, aber der Kunde erhält nichts. Lesen Sie ok und error der Antwort von POST /api/v1/messages: numero_sem_whatsapp bedeutet, dass diese Telefonnummer kein WhatsApp hat; Fehler, die mit evolution_ beginnen, sind fast immer das getrennte Handy des Unternehmens — lesen Sie den QR-Code erneut.
Doppelte Antwort. Verwenden Sie message.id als Schlüssel: Dasselbe Ereignis kann mehr als einmal eintreffen.
Bereit zur Integration?
Erzeugen Sie Ihren API-Schlüssel unter Integrationen — mehr braucht Ihr System nicht.