Chatbot über die Backend-API einbinden

Diese Seite richtet sich an Entwickler, die den Chatbot ohne das fertige Skript chatbot.js direkt über die Backend-API ansprechen möchten – etwa um eine vollständig eigene Chat-Oberfläche zu bauen oder den Chatbot in eine native App zu integrieren.

Für die Standard-Einbindung als schwebendes Chat-Fenster verwenden Sie stattdessen das Skript chatbot.js, siehe Chatbot in eine Webseite einbinden.

Grundlagen

Basis-URL: https://<ihre-skai-instanz>/api/v1
Alle Anfragen erfolgen per HTTPS, Anfrage- und Antwortkörper sind JSON.
Das Streaming der Antworten erfolgt über eine WebSocket-Verbindung (wss://).
Alle hier beschriebenen Endpunkte verwenden das Chatbot-Token zur Authentifizierung; eine Benutzeranmeldung ist nicht erforderlich.

Authentifizierung

Jeder Aufruf wird mit dem Chatbot-Token authentifiziert. Das ist ein JWT, das fest an genau einen Chatbot gebunden ist. Sie finden es in der Detailansicht des Chatbots unter Einbinden – es ist derselbe Wert, der bei chatbot.js im Attribut data-token verwendet wird.

Das Token kann auf zwei Wegen übergeben werden:

als HTTP-Header Authorization: Bearer <token> – empfohlen für REST-Aufrufe, oder
als Query-Parameter ?token=<token> – nötig für die WebSocket-Verbindung, da dort keine eigenen Header gesetzt werden können.

Typischer Ablauf

Optional: Konfiguration des Chatbots laden – GET /chatbot/self.
Einen Chat starten – POST /chatbot-chat. Die Antwort enthält die id des Chats.
WebSocket öffnen, Prompt senden und die gestreamte Antwort empfangen.
Optional: Verlauf nachladen, Chat schließen, Besucher an-/abmelden.

REST-Endpunkte

Methode	Pfad	Zweck
`GET`	`/chatbot/self?language=<sprache>`	Öffentliche Konfiguration des Chatbots abrufen.
`POST`	`/chatbot-chat`	Neuen Chat starten.
`POST`	`/chatbot-chat/{chatId}`	Verlauf und Metadaten eines Chats abrufen.
`POST`	`/chatbot-chat/{chatId}/close`	Chat beenden.
`POST`	`/chatbot-chat/{chatId}/sign-in`	Angemeldeten Besucher dem Chat zuordnen.
`POST`	`/chatbot-chat/{chatId}/sign-off`	Besucher wieder abmelden.
`GET`	`/chatbot/source-reference?sourceDocumentId=<id>`	Quellenangaben zu Wissensdokumenten auflösen (mehrfach angebbar).
`GET`	`/chatbot-chat/{chatId}/attachment/{attachmentId}/download-chatbot`	Anhang aus dem Chat herunterladen.

Konfiguration abrufen

GET /api/v1/chatbot/self?language=Deutsch
Authorization: Bearer <token>

Die Antwort enthält die für die Darstellung relevanten Felder, u. a.:

{
  "id": "…",
  "spaceId": "…",
  "displayName": "skai",
  "aiName": "skai",
  "theme": { "primaryColor": "#0B5E8A", "secondaryColor": "#FFFFFF", "fontSize": "MEDIUM" },
  "initialMessageComponents": [ … ],
  "concludingMessageComponents": [ … ],
  "requestSuggestionsAllowed": true,
  "requestUserData": false,
  "allowTextToSpeech": true,
  "allowSpeechToText": true,
  "showCloseConfirmationDialog": false,
  "restrictEmbeddingWebsites": true,
  "registeredEmbeddingWebsiteUrls": [ "https://ihre-domain.de" ],
  "activated": true
}

Chat starten

POST /api/v1/chatbot-chat Authorization: Bearer <token> Content-Type: application/json { "initialLocale": "de-DE", "userData": { "userName": "John Doe", "userEmail": "[email protected]" }, "clientData": { "token": "eyJhbGciOiJIUzI1N..." } }

initialLocale (erforderlich) – Sprach-/Ländercode des Besuchers (z. B. de-DE).
userData (optional) – Name und E-Mail des Besuchers, falls bekannt.
clientData (optional) – Signiertes Client-Daten-Token mit Anmeldedaten, Kontext und Tools (siehe Chatbot in eine Webseite einbinden).

Die Antwort ist das Chat-Objekt; entscheidend ist das Feld id – die chatId, die Sie für die WebSocket-Verbindung und alle weiteren Aufrufe benötigen:

{
  "id": "8f3c…",
  "chatbotId": "…",
  "spaceId": "…",
  "initialLocale": "de-DE",
  "createdAt": "2026-06-15T08:00:00Z",
  "expiresAt": "2026-09-15T08:00:00Z",
  "messages": [],
  "attachments": [],
  "events": [],
  "topicTags": [],
  "userData": null
}

Weitere REST-Aufrufe

Die folgenden Aufrufe erwarten als Körper optional bzw. erforderlich das Client-Daten-Token:

POST /api/v1/chatbot-chat/{chatId}          # Verlauf laden     – Body: { "clientData": { "token": "…" } } (optional)
POST /api/v1/chatbot-chat/{chatId}/close    # Chat beenden       – Body: { "clientData": { "token": "…" } } (optional)
POST /api/v1/chatbot-chat/{chatId}/sign-in  # Besucher anmelden  – Body: { "clientData": { "token": "…" } } (erforderlich)
POST /api/v1/chatbot-chat/{chatId}/sign-off # Besucher abmelden  – Body: { "clientData": { "token": "…" } } (erforderlich)

POST /chatbot-chat/{chatId} liefert den Verlauf (messages), Ereignisse (events, z. B. Übergabe an einen Mitarbeiter), Anhänge sowie closed und createdAt zurück.

Nachrichten streamen (WebSocket)

Die eigentliche Konversation läuft über eine WebSocket-Verbindung. Bauen Sie diese mit der zuvor erhaltenen chatId auf und übergeben Sie das Token als Query-Parameter:

wss://<ihre-skai-instanz>/api/v1/chatbot-chat/{chatId}/streaming/ws?token=<token>

Über die Verbindung werden in beide Richtungen JSON-Textnachrichten ausgetauscht. Jede Nachricht besitzt ein Feld type und eine requestId (eine vom Client erzeugte UUID, über die sich die Server-Antworten der jeweiligen Anfrage zuordnen lassen).

Nachrichten vom Client an den Server

Ein Prompt wird in zwei Schritten gesendet: zuerst eine promptInit-Nachricht mit den Parametern, danach der Prompt-Text als ein oder mehrere promptChunk-Nachrichten. Erst die letzte promptChunk-Nachricht (chunkIndex == totalChunks - 1) löst die Verarbeitung aus.

// 1) Parameter der nächsten Anfrage
{ "type": "promptInit", "language": "Deutsch", "requestId": "3b1e…" }

// 2) Prompt-Text (hier als ein einziger Chunk)
{ "type": "promptChunk", "chunk": "Wie lauten Ihre Öffnungszeiten?", "chunkIndex": 0, "totalChunks": 1, "requestId": "3b1e…" }

Weitere Client-Nachrichten:

`type`	Felder	Zweck
`promptInit`	`language`	Antwortsprache für den folgenden Prompt setzen (z. B. `Deutsch`).
`promptChunk`	`chunk`, `chunkIndex`, `totalChunks`	Prompt-Text (ggf. stückweise) übertragen.
`cancelResponse`	–	Die laufende Antwort abbrechen.
`chatbotSuggestions`	–	Vorschläge für Folgefragen anfordern.
`chatbotUpdateClientData`	`token`	Client-Daten-Token zur Laufzeit aktualisieren.
`toolExecutionResponse`	`resultToken`	Ergebnis einer clientseitigen Tool-Ausführung zurückgeben.
`ping`	–	Verbindung aktiv halten; der Server antwortet mit `{ "type": "pong" }`.

Nachrichten vom Server an den Client

Während der Beantwortung sendet der Server eine Folge von Ereignissen. Die wichtigsten:

`type`	Felder	Bedeutung
`messageStart`	`author`, `pseudonyms?`	Beginn einer Antwortnachricht.
`messageChunk`	`chunk`	Ein Textstück der Antwort (fortlaufend anzuhängen).
`messageDone`	`files`	Antwort vollständig; ggf. mit erzeugten Dateien.
`toolStart`/`toolDone`	`toolExecution`	Ein Tool wird ausgeführt bzw. ist fertig.
`preToolExecution`	`preToolExecution`	Ankündigung einer bevorstehenden Tool-Ausführung.
`toolExecutionRequest`	`token`	Aufforderung zur clientseitigen Tool-Ausführung (Antwort via `toolExecutionResponse`).
`chatbotSuggestions`	`suggestions`	Vorgeschlagene Folgefragen.
`chatbotHandoverCheckStart`/`chatbotHandoverCheckEnd`	`shouldHandover`	Prüfung bzw. Ergebnis einer möglichen Übergabe an einen Mitarbeiter.
`error`	`error`	Ein Fehler ist aufgetreten (Feld `error` enthält den Fehlertyp).

Ein typischer Ablauf einer Antwort sieht so aus:

{ "type": "messageStart", "requestId": "3b1e…" }
{ "type": "messageChunk", "chunk": "Unsere ",        "requestId": "3b1e…" }
{ "type": "messageChunk", "chunk": "Öffnungszeiten…", "requestId": "3b1e…" }
{ "type": "messageDone",  "files": [], "requestId": "3b1e…" }

Weitere WebSocket-Kanäle

Für denselben Chat stehen zusätzlich folgende Kanäle bereit (Authentifizierung wie oben über ?token=):

…/chatbot-chat/{chatId}/file-upload/ws – Datei-Upload (binär).
…/chatbot-chat/{chatId}/tts/ws – Text-to-Speech: Text rein, Audio (binär) raus.
…/chatbot-chat/{chatId}/stt/ws?mimeType=<typ> – Speech-to-Text: Audio rein, Transkript raus.

Hinweise

Domains: Die unter Beschränkungen hinterlegte Domain-Liste (registeredEmbeddingWebsiteUrls) schützt die Einbettung über chatbot.js. Bei direkter Nutzung der API liegt der Schutz des Tokens in Ihrer Verantwortung.
Verbrauch: Jeder Chat zählt gegen die Credits der Organisation und die für den Chatbot konfigurierten Limits.
Aufbewahrung: Chatverläufe werden 3 Monate gespeichert; jeder Chat besitzt ein expiresAt.
Tools: Stellt der Chatbot clientseitige Tools bereit, gelten für Signierung und Validierung die unter Chatbot in eine Webseite einbinden beschriebenen Regeln (RS256, serverseitige Validierung).

15 June 2026