Chatbot-API
Eine Chatbot-API für deine Apps, dein Backend und deine Daten
Über die REST-API von intoCHAT spricht dein Server mit dem Agenten, den du im Dashboard trainiert hast. Sende eine Nachricht und bekomm dieselbe Antwort wie im Chat-Widget, lies Gespräche und Leads, halte Kontakte synchron, ergänze Wissen und abonniere Webhooks, mit JSON über HTTPS und einer OpenAPI-3.1-Spezifikation für jeden Endpunkt.
Dein Chatbot sollte nicht am Website-Widget enden
Das Widget deckt die Besucher deiner Website ab. Dieselben Fragen kommen aber auch in deiner Mobile-App, deinem Kundenportal, einem internen Tool oder einem Support-Formular an, und die Gespräche und Leads, die der Agent sammelt, gehören in dein CRM, dein Data Warehouse oder dein Ticketsystem, nicht nur in ein Dashboard. Wer den Bot für jeden Ort neu baut, pflegt eine zweite Wissensbasis und ein zweites Regelwerk, die langsam auseinanderlaufen. Mit einer Chatbot-API nutzt jeder Kanal, den du baust, den einen Agenten, den du schon trainiert hast, und deine eigenen Systeme lesen, was er gelernt hat.
Was dir die Chatbot-API bringt
Ein Agent, einmal trainiert, antwortet überall, wo dein Code läuft.
Derselbe Agent, dieselben Antworten
Eine Antwort über die API entsteht im selben Code wie eine Antwort im Widget, aus demselben Wissen, denselben Anweisungen und demselben Modell. Deine API-Aktionen, eigenen Buttons, Chat-Formulare und Terminbuchungen funktionieren auch in API-Chats.
Gespräche, die weitergehen
Übergib eine eigene sessionId, etwa deine User-ID, und dieselbe Person setzt immer dasselbe Gespräch fort. Der Agent sieht die letzten 40 Nachrichten als Verlauf, und jeder API-Chat erscheint im Tab Conversations neben den Widget-Chats.
Deine Daten in deinen Systemen
Blättere durch Gespräche mit vollständigen Transkripten, Leads mit ihren eigenen Feldern und Kontakte, die neuesten zuerst, mit dem Parameter since für inkrementelle Syncs. Die Reihenfolge ist fest, also wird nichts doppelt gelesen oder übersprungen, während neue Chats eingehen.
Ein Schlüssel mit Scopes pro Aufgabe
Gib jeder Integration einen eigenen Schlüssel mit genau den Scopes, die sie braucht, zum Beispiel conversations:read für einen Report und chat für deine App. Schlüssel gehören dem Konto, nicht einer Person, und funktionieren nicht mehr, sobald du sie widerrufst.
Eine OpenAPI-Spezifikation als Startpunkt
Jeder Endpunkt, jedes Feld, jeder Fehler und jeder Webhook-Inhalt ist in einer OpenAPI-3.1-Datei beschrieben. Importiere sie in Postman oder Insomnia oder erzeuge mit einem Tool wie OpenAPI Generator eine Client-Bibliothek.
So startest du mit der Chatbot-API
Trainiere deinen Agenten
Lege den Agenten im Dashboard an, füge deine Website, Dateien oder Q&A hinzu und lege Anweisungen und Modell fest. Die API nutzt den Agenten genau so, wie er dort eingerichtet ist; Agenten legst du im Dashboard an und änderst sie dort, nicht über die API.
Erstelle einen API-Schlüssel
Klicke in der Seitenleiste unter Settings auf API keys. Gib dem Schlüssel einen Namen, behalte Every scope, including ones added later oder wähle Only the scopes I choose, und klicke auf Create key. Kopiere den Schlüssel, der mit ic_live_ beginnt, in eine Umgebungsvariable auf deinem Server: Er wird nur einmal angezeigt.
Sende deine erste Nachricht
Schicke die Nachricht per POST an /api/v1/agents/{agentId}/chat, mit dem Schlüssel als Bearer-Token im Authorization-Header. Die JSON-Antwort enthält die Antwort, die conversationId und sessionId zum Weiterchatten, die genutzten Quellen und gegebenenfalls Folgefragen, Buttons, Produkte, Formulare oder freie Termine. Mit stream: true bekommst du den Text, während er geschrieben wird.
Synchronisieren und abonnieren
Lies Gespräche, Leads und Kontakte regelmäßig mit since, ergänze Textschnipsel oder Q&A-Paare, wenn sich deine Inhalte ändern, und abonniere einen Webhook für Events wie lead.created oder handoff.requested, damit sie deinen Server erreichen, sobald sie passieren.
Die Chatbot-API im Detail
Nachricht senden
Der Chat-Endpunkt nimmt eine Nachricht mit bis zu 10.000 Zeichen, optional eine conversationId oder sessionId zum Fortsetzen, stream für gestreamten Text und timeZone für Terminzeiten. Ohne eine der beiden IDs beginnt jede Nachricht ein neues Gespräch.
Strukturierte Antwortfelder
Neben der Antwort in Markdown enthält die Response die genutzten Seiten, vorgeschlagene Folgefragen, eigene Buttons, Produktkarten mit Preis und Verfügbarkeit, ein angebotenes Chat- oder Lead-Formular, freie Termine, Rich-Reply-Blöcke wie Tabellen und Karten und den Live-Chat-Status.
Kennt den Live-Chat
Hat jemand aus deinem Team das Gespräch in der Live-Chat-Inbox übernommen, wird deine Nachricht gespeichert, die Antwort bleibt leer und liveChat steht auf paused. Die Antworten deiner Kollegin liest du samt Vorname über den Gesprächs-Endpunkt. Solche Nachrichten verbrauchen keine Nachrichten deines Plans.
Gespräche und Inbox
Liste die Gespräche eines Agenten aus Widget und API mit Themen, Stimmung, Live-Chat-Status und CSAT-Bewertung auf, filtere nach Inbox-Status und hol dir eines mit allen Nachrichten. Mit conversations:write setzt du Inbox-Status, Priorität, Tags und zuständige Person.
Leads und Kontakte
Liste Leads mit Name, E-Mail, Telefon und deinen eigenen Formularfeldern auf. Lege Kontakte über deine eigene externe ID oder die E-Mail an oder aktualisiere sie, mit bis zu 50 eigenen Attributen pro Kontakt, damit die Kontakte des Agenten zu den Nutzern deiner App passen.
Wissen, das du aktualisieren kannst
Liste die Quellen eines Agenten mit ihrem Trainingsstatus auf, füge einen Textschnipsel oder ein Q&A-Paar hinzu, das sofort trainiert wird, und lösche eine Quelle samt allem, was der Agent daraus gelernt hat. Ein Q&A-Paar mit derselben Frage wird aktualisiert statt verdoppelt.
Webhooks und Events
Abonniere bis zu 25 Webhooks pro Agent für Events wie lead.created, form.submitted, booking.created, handoff.requested und conversation.status_changed, jeder mit eigenem Signatur-Secret. Oder frag die neuesten Events einer Art ab, genau so aufgebaut wie eine Webhook-Zustellung.
Klare Limits und Fehler
Jeder Schlüssel kann 60 Anfragen pro Minute stellen, und jede Antwort trägt X-RateLimit-Header. Fehler haben immer dieselbe JSON-Form mit einem festen Code wie insufficient_scope, rate_limited oder message_limit_reached, sodass dein Code jeden Fall behandeln kann.
Häufige Fragen
Was ist eine Chatbot-API?
Über eine Chatbot-API schickt deine eigene Software Nachrichten an einen Chatbot und bekommt seine Antworten, statt nur über ein Chatfenster auf einer Website. Die REST-API von intoCHAT macht das für den Agenten, den du im Dashboard trainiert hast, und lässt deinen Server außerdem Gespräche, Leads und Kontakte lesen, sein Wissen aktualisieren und seine Events abonnieren.
Welchen Plan brauche ich für die API?
Die API ist in Starter, Pro und Enterprise enthalten. Im Free-Plan kannst du keine Schlüssel erstellen. Wechselt ein Konto zurück zu Free, beantworten seine bestehenden Schlüssel jede Anfrage mit dem Fehler plan_required und funktionieren wieder, sobald das Konto mindestens Starter hat.
Zählen API-Antworten als Nachrichten?
Ja. Jede Antwort, die der Agent über die API schreibt, zählt auf deinen Plan genau wie eine Antwort im Widget: eine Nachricht mit dem Standardmodell, mehr mit einem größeren Modell, und auf die monatliche Obergrenze des Agenten, falls du eine gesetzt hast. Gespräche, Leads und Kontakte lesen und Quellen hinzufügen oder löschen kostet keine Nachrichten.
Kann ich die API aus dem Browser oder meinem Embed-Code aufrufen?
Nein. Die API ist für Server: Sie sendet keine CORS-Header, und einen Schlüssel in einer Webseite könnte jeder kopieren. Um einen Chat auf deiner Website zu zeigen, nutze das Script-Tag oder das JavaScript-SDK und ruf die API aus deinem Backend auf. Nur die OpenAPI-Spezifikation lässt sich von jeder Website laden.
Wie setze ich ein Gespräch fort?
Sende die conversationId einer früheren Antwort oder deine eigene sessionId, etwa deine User-ID: Dieselbe sessionId setzt immer dasselbe Gespräch fort. Über die API lassen sich nur Gespräche fortsetzen, die über die API begonnen wurden, und der Agent sieht die letzten 40 Nachrichten als Verlauf.
Welche Ratenlimits gelten?
Jeder Schlüssel kann 60 Anfragen pro Minute über alle Endpunkte stellen, und ein Konto kann bis zu 20 aktive Schlüssel haben. Ein Agent beantwortet höchstens 1.000 Nachrichten pro Stunde, Widget und API zusammen, und eine Antwort muss innerhalb von 55 Sekunden fertig sein, sonst endet die Anfrage mit einem Timeout-Fehler.
Was kann die API noch nicht?
Es gibt noch keine Endpunkte, um Agenten anzulegen oder zu ändern, Chat-Formulare abzuschicken, Termine zu buchen oder Live-Chats zu übernehmen. Über die API fügst du Textschnipsel und Q&A-Paare hinzu; Webseiten, Dateien und Notion-Seiten kommen über das Dashboard dazu. API-Nachrichten können keine Dateien enthalten, und Client-Aktionen, die im Browser eines Besuchers laufen, werden in API-Chats nicht angeboten.
Was ist der Unterschied zu KI-Aktionen?
Sie arbeiten in entgegengesetzte Richtungen. Bei KI-Aktionen ruft der Agent während eines Chats deine API auf, um etwas nachzuschlagen, etwa eine Bestellung oder ein Kundenkonto. Bei der Chatbot-API ruft dein Server intoCHAT auf, um Nachrichten zu senden und Daten zu lesen. Viele Setups nutzen beides.
Bau auf dem Agenten auf, den du schon trainiert hast
Erstelle deinen Agenten kostenlos und trainiere ihn mit deiner Website, wechsle dann zu Starter, erstelle einen API-Schlüssel und sende deine erste Nachricht mit einem einzigen curl-Befehl.
Agent kostenlos erstellenKostenloser Plan, keine Kreditkarte nötig.