# Antworten generieren

Über /answer-generations erzeugen Sie eine Chatbot-Antwort auf eine Nutzer*innen-Nachricht. Um eine neue Konversation zu beginnen, lassen Sie den Parameter conversationId leer bzw. ungesetzt. Um eine bestehende Konversation weiterzuführen, senden Sie die conversationId aus der letzten Antwort des Chatbots mit.

Die Antwort wird standardmäßig als Server-Sent-Event-Stream ausgeliefert, siehe Streaming .

Voraussetzungen für alle Anfragen (Basis-URL, Authorization- und kauz-chatbot-Header) finden Sie im Überblick .

# POST `/partner/v1/answer-generations`

# Anfrage

Feld	Typ	Pflicht	Beschreibung
`message`	string	ja	Die zu beantwortende Nutzer*innen-Nachricht.
`inputType`	string	ja	Art der Eingabe: `freeText` (getippter Freitext), `clickOption` (angeklickte Auswahloption) oder `voice` (Spracheingabe).
`meta`	object	ja	Zusätzliche Metadaten zur Anfrage, siehe unten.
`meta.conversationLanguage`	string	ja	Sprache, in der die Konversation geführt wird (z. B. `EN`).
`meta.referrer`	string	ja	Referrer, aus dem die Konversation stammt.
`meta.userCategory`	string	nein	Kategorie derdes fragenden Nutzerin.
`senderId`	string	nein	Kennung derdes Endnutzerin, die*der die Nachricht sendet.
`clickOptionReactionId`	string	nein	Reaktions-ID der angeklickten Option – erforderlich, wenn `inputType` den Wert `clickOption` hat.
`conversationId`	string	nein	Bestehende Konversation, die fortgeführt werden soll. Weglassen, um eine neue Konversation zu beginnen.
`stream`	boolean	nein	Antwort als Server-Sent Events streamen. Standardwert ist `true`.

# Antwort

Feld	Typ	Beschreibung
`id`	string	Eindeutige ID der Antwortnachricht.
`chatbot`	string	Name des Chatbots, der die Antwort erzeugt hat.
`inputEventId`	string	ID des gespeicherten Nutzer*innen-Nachrichten-Events, auf das diese Antwort reagiert.
`date`	string	Zeitpunkt der Erzeugung (ISO 8601).
`conversationId`	string	ID der Konversation. Für die nächste Anfrage als `conversationId` übergeben, um die Konversation fortzuführen.
`content.text`	string	Antworttext inkl. Markup.
`content.plainText`	string	Antworttext als reiner Text.
`content.actions[]`	array	Aktionen, die der Chatbot an die Antwort angehängt hat und die vom Client interpretiert werden: je `command` und `parameters[]` mit `name`/`value`.
`content.card`	object	An die Antwort angehängte Adaptive Card: `payload` (serialisiert) und `data` (an die Karte gebundene Daten).
`links.relation`	string	Bezug des Links zur Antwort: `RESPONSE` oder `QUESTION`.
`links.target`	string	Ziel des Links.
`meta.answerType`	string	Wie die Antwort entstanden ist: `PREDEFINED` (hinterlegter Inhalt), `GENERATED` (generierter Inhalt) oder `SYSTEM` (Systemnachricht).
`meta.conversationLanguage`	string	Sprache, in der die Konversation geführt wird (i18n-Code).
`meta.referrer`	string	Referrer der Anfrage, die zu dieser Antwort geführt hat.
`sender.id`	string	Kennung derdes Absenderin der Antwort.
`sender.type`	string	Typ derdes Absenderin: `USER` oder `BOT`.
`tokenDelta`	string	Textinkrement dieses Chunks – nur in SSE-Chunks vorhanden, wenn `stream` den Wert `true` hat.
`step`	string	Name des Verarbeitungsschritts, der diesen Chunk erzeugt hat – nur in SSE-Chunks.
`final`	boolean	Kennzeichnet den abschließenden SSE-Chunk, der die vollständige Antwort trägt. Standardwert `false`.

{
  "message": "string",
  "inputType": "freeText",
  "meta": {
    "conversationLanguage": "string",
    "referrer": "string",
    "userCategory": "string"
  },
  "senderId": "string",
  "clickOptionReactionId": "string",
  "conversationId": "string",
  "stream": true
}

{
  "id": "string",
  "chatbot": "string",
  "inputEventId": "string",
  "date": "string",
  "conversationId": "string",
  "content": {
    "text": "string",
    "plainText": "string",
    "actions": [
      {
        "command": "string",
        "parameters": [
          {
            "name": "string",
            "value": "string"
          }
        ]
      }
    ],
    "card": {
      "payload": "string",
      "data": {}
    }
  },
  "links": {
    "relation": "RESPONSE",
    "target": "string"
  },
  "meta": {
    "answerType": "GENERATED",
    "conversationLanguage": "string",
    "referrer": "string"
  },
  "sender": {
    "id": "string",
    "type": "BOT"
  },
  "tokenDelta": "string",
  "step": "string",
  "final": false
}

curl --location --request POST "https://example.kauz.ai/partner/v1/answer-generations" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"message\":\"Hallo, wie kannst du mir helfen?\",
   \"inputType\":\"freeText\",
   \"stream\":false,
   \"meta\":{
      \"conversationLanguage\":\"DE\",
      \"referrer\":\"https://example.com/hilfe\"
   }
}"

{
  "id": "51a156da-9393-4a0a-af1e-e76d4d5dbfc7",
  "chatbot": "helpdesk",
  "inputEventId": "a0f2c1de-5f0b-4c1e-9d33-1b8a1f0c4e77",
  "date": "2026-07-24T16:21:22.720Z",
  "conversationId": "a311a62f-8e01-445a-89e2-186ebf016d55",
  "content": {
    "text": "Guten Tag! Sie können mich alles über unsere Produkte und Dienstleistungen fragen.",
    "plainText": "Guten Tag! Sie können mich alles über unsere Produkte und Dienstleistungen fragen.",
    "actions": []
  },
  "meta": {
    "answerType": "PREDEFINED",
    "conversationLanguage": "DE",
    "referrer": "https://example.com/hilfe"
  },
  "sender": {
    "id": "73acad72-7827-4fde-b398-c59607a42826",
    "type": "BOT"
  }
}

# Konversation fortführen

Die Antwort enthält eine conversationId. Übergeben Sie diese in der nächsten Anfrage, damit der Chatbot den bisherigen Gesprächsverlauf berücksichtigt:

curl --location --request POST "https://example.kauz.ai/partner/v1/answer-generations" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"message\":\"Und was kostet das?\",
   \"inputType\":\"freeText\",
   \"conversationId\":\"a311a62f-8e01-445a-89e2-186ebf016d55\",
   \"stream\":false,
   \"meta\":{
      \"conversationLanguage\":\"DE\",
      \"referrer\":\"https://example.com/hilfe\"
   }
}"

# Streaming

Der Parameter stream steuert die Auslieferung der Antwort:

stream: false – die vollständige Antwort wird als einzelner JSON-Körper zurückgegeben.
stream: true (Standard) – die Antwort wird als text/event-stream ausgeliefert.

Beim Streaming ist jedes data:-Payload ein JSON-serialisierter Antwort-Chunk mit derselben Struktur wie der nicht-gestreamte Körper. tokenDelta enthält dabei das Textinkrement, step den Namen des Verarbeitungsschritts. Der abschließende Chunk trägt final: true und die vollständige Antwort.

data: {"conversationId":"a311a62f-...","step":"answer","tokenDelta":"Guten "}

data: {"conversationId":"a311a62f-...","step":"answer","tokenDelta":"Tag!"}

data: {"id":"51a156da-...","conversationId":"a311a62f-...","content":{"text":"Guten Tag!","plainText":"Guten Tag!"},"final":true}

Tritt nach Beginn des Streamings ein Fehler auf, wird ein abschließendes Event app-error gesendet und der Stream geschlossen – siehe Fehler während eines Streams .

# Darstellung der Antwortinhalte

Das Feld content.text enthält überwiegend Markdown, wie es für LLMs typisch ist, sowie einzelne Kauz-spezifische Markup-Elemente. Wie Sie diese Inhalte verarbeiten und rendern, beschreibt die Dokumentation zum Kauz-Markup.

Kauz-Markup

../kauz-markup/