Powered by

# Umstieg von der Dialog-API

Diese Anleitung führt Sie durch den Umstieg von POST /api/v4/dialogues/question (Dialog-API mit SSE-Streaming) auf die Partner-API, wenn Sie ein eigenes Chatbot-Frontend betreiben. Nutzen Sie stattdessen den synchronen Endpunkt POST /api/v4/dialogues/question/sync mit Basic-Authentifizierung, beachten Sie zusätzlich Umstieg von /question/sync .

Die wichtigsten Änderungen im Überblick:

  • Aufrufe erfolgen nur noch von einem Server aus.
  • Die Authentifizierung erfolgt über OAuth 2.0 (Client Credentials) statt über Basic-Authentifizierung bzw. Chat-Token.
  • Einige Feldnamen in Anfrage und Antwort ändern sich.
  • Fehler während eines Streams kommen als Event app-error statt custom-error.

Die vollständige Beschreibung der neuen Endpunkte finden Sie unter Antworten generieren und Analytics-Events , Authentifizierung und Fehlerbehandlung im Partner-API-Überblick .

# 1. Architektur

Die Partner-API wird nur von einem Server aus aufgerufen. Das client_secret darf nie in den Browser gelangen. Die Partner-API erlaubt außerdem kein CORS, Aufrufe direkt aus dem Browser funktionieren also nicht.

  • Ruft Ihr Frontend die Dialog-API heute direkt aus dem Browser auf, benötigen Sie einen eigenen Backend-Proxy, der den SSE-Stream an den Browser weiterreicht.
  • Ist kein Streaming nötig, geht es mit stream: false einfacher. Die Antwort kommt dann als einzelnes JSON-Objekt.
  • Ist ein Chatbot heute per Login geschützt (OAuth- oder Credentials-Login), entfällt diese Prüfung auf Kauz-Seite. Sie authentifizieren Ihre Nutzer*innen künftig selbst in Ihrem Backend.

# 2. Authentifizierung

Statt Basic-Authentifizierung (username:API_KEY) bzw. Chat-Token kommt OAuth 2.0 mit dem Client-Credentials-Grant zum Einsatz. Origin-Prüfung und Login-Sitzungen der Endnutzer*innen fallen weg.

  • Token anfordern: POST …/auth/realms/{realm}/protocol/openid-connect/token mit grant_type=client_credentials, client_id und client_secret.
  • {realm} ist Ihre client_id.
  • Die Zugangsdaten (client_id / client_secret) legen Sie im aiStudio unter Partner-API-Zugriff an.
  • Das Token gilt 15 Minuten (expires_in: 900). Fordern Sie danach einfach ein neues an; ein Refresh-Token gibt es nicht.
  • Header bei jeder Anfrage: Authorization: Bearer <token>.
  • Header bei jeder Anfrage: kauz-chatbot: <chatbot-name> (neu). Der Chatbot muss zum Client gehören, sonst antwortet die API mit 403. Fehlt der Header, antwortet sie mit 401.

Ein vollständiges Beispiel finden Sie unter Authentifizierung .

# 3. Pfade

Zweck Dialog-API Partner-API
Antwort generieren POST /api/v4/dialogues/question POST /partner/v1/answer-generations
Analytics/Feedback POST /api/v4/dialogues/analytics POST /partner/v1/events/analytics

# 4. Anfrage: Antwort generieren

Dialog-API Partner-API
question message
conversation conversationId
inputType (beliebiger String) inputType, nur noch freeText / clickOption / voice / form
meta.chat_i18n_language meta.conversationLanguage
meta.referrer (optional) meta.referrer (Pflicht)
meta.userCategory, senderId, clickOptionReactionId unverändert
meta.realm, meta.lang, meta.deviceType entfallen. Werden ohne Fehlermeldung verworfen.
customer, product, instanceGroup, chatbotType, raw entfallen. Kunde und Chatbot ergeben sich aus Token und kauz-chatbot-Header.
– stream: true (Standard) liefert SSE, false liefert ein einzelnes JSON-Objekt.

# 5. Antwort

Die Änderungen gelten für jeden SSE-Chunk und für die JSON-Antwort bei stream: false.

Dialog-API Partner-API
conversation conversationId
questionEventId inputEventId
group chatbot
meta.answer_type meta.answerType
meta.chat_i18n_language meta.conversationLanguage
– meta.referrer (neu)
id, date, sender, content.*, tokenDelta, step, final, links unverändert
type, meta.lang, meta.sources, meta.deviceType, sourcesPending, actions (oberste Ebene) entfallen. actions steht weiterhin in content.actions.

# 6. Anfrage: Analytics/Feedback

Dialog-API Partner-API
conversation conversationId
customer client (weiterhin Pflicht)
meta (optional) meta (Pflicht, mit meta.referrer als Pflichtfeld)
senderId, target, tags, data unverändert. tags enthält genau ein Element.
product, raw entfallen

# 7. Fehlerbehandlung

  • Fehler, die vor dem Stream auftreten, kommen als JSON-Objekt mit statusCode, message, correlationId und optional errorCode.
  • Fehler während des Streams kommen als letztes Event, danach wird der Stream geschlossen. Das Event heißt jetzt app-error statt bisher custom-error. Benennen Sie Ihren Listener entsprechend um.
  • Die Fehlercodes heißen jetzt PA_ERR_xxxx statt ERR_xxxx. Nicht jeder bisherige Code hat eine Entsprechung; in dem Fall fehlt errorCode. Wenn Sie auf bestimmte Codes prüfen, gleichen Sie diese mit der Fehlercode-Tabelle ab.
  • Geben Sie bei Fehlern immer die correlationId an den Support weiter.

# 8. Umstieg von /question/sync

Haben Sie mit Basic-Authentifizierung integriert, nutzen Sie seit Release 6.40.1 den synchronen Endpunkt POST /api/v4/dialogues/question/sync. Für Sie gilt:

  • Die Abschnitte 1, 2, 4, 5 und 7 gelten auch für Sie. Wo die folgende Tabelle davon abweicht oder etwas ergänzt, hat die Tabelle Vorrang.
  • Statt des Pfads aus Abschnitt 3 stellen Sie /api/v4/dialogues/question/sync auf /partner/v1/answer-generations um.
  • Abschnitt 6 betrifft Sie, wenn Sie Analytics-Events senden möchten. Seit Release 6.40.1 akzeptiert /api/v4/dialogues/analytics keine Basic-Authentifizierung mehr; mit Basic-Authentifizierung können Sie seitdem keine Analytics-Events senden. Mit der Partner-API ist das wieder möglich.
Dialog-API (/question/sync) Partner-API
Synchrone JSON-Antwort stream: false setzen. Die Antwort kommt dann als einzelnes JSON-Objekt.
Basic-Authentifizierung (username:API_KEY) OAuth 2.0, siehe Authentifizierung
chatbot und meta.chatbot im Request entfallen. Der Chatbot wird über den Header kauz-chatbot angegeben.
customer, instanceGroup, product (Pflicht) entfallen. Kunde und Chatbot ergeben sich aus Token und kauz-chatbot-Header.
inputType (optional, bereits auf freeText / clickOption / voice / form beschränkt) inputType (Pflicht), erlaubte Werte unverändert
raw, meta.deviceType im Request Kamen bei /question/sync nicht vor und wurden verworfen. Die Angaben dazu in Abschnitt 4 betreffen Sie nicht.
chatbot in der Antwort unverändert
type, meta.lang, meta.sources in der Antwort entfallen. meta.deviceType, sourcesPending und actions auf oberster Ebene aus Abschnitt 5 kamen bei /question/sync nicht vor.
– tokenDelta, step, final: nur in SSE-Chunks, bei stream: false nicht relevant.