Powered by

# Analytics-Events

Analytics-Events halten Interaktionen der Chatbotnutzer*innen fest, die nicht Teil des Nachrichtenverlaufs sind – etwa das Klicken eines Links, das Bewerten einer Antwort oder das Wechseln der Chatsprache. Über /events/analytics melden Sie diese Ereignisse aus Ihrem eigenen Frontend an die Kauz-Plattform, wo sie im Editor-Reporting ausgewertet werden können.

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

# POST /partner/v1/events/analytics

Alle Payloads teilen sich dieselben Felder. Welche Struktur data hat und worauf sich target bezieht, bestimmt der Tag in tags.

Feld Typ Pflicht Beschreibung
conversationId string ja ID der Konversation, zu der das Event gehört – die conversationId aus der Antwortgenerierung .
client string ja Name des Clients, unter dem das Event erfasst wird.
tags array ja Genau ein Element. Der Tag bestimmt die Struktur von data und target – siehe Unterstützte Events .
target object ja Objekt, auf das sich das Event bezieht: id und type (MESSAGE oder CONVERSATION).
data object ja Nutzdaten des Events. Struktur je nach Tag – bei Events ohne Nutzdaten ein leeres Objekt.
meta object ja Zusätzliche Metadaten als Schlüssel-Wert-Paare mit String-Werten. Der Schlüssel referrer ist erforderlich.
senderId string nein Kennung der*des Endnutzer*in, die*der das Event ausgelöst hat – dieselbe senderId wie bei der Antwortgenerierung.

# Target-Typen

Typ id Verwendung
MESSAGE ID der Nachricht Das Event bezieht sich auf eine einzelne Bot-Nachricht.
CONVERSATION ID der Konversation Das Event bezieht sich auf die gesamte Konversation.

# Unterstützte Events

Die folgende Tabelle listet alle Tags mit standardisierten Datenfeldern, die im Editor-Reporting dargestellt werden können. Ein – in der letzten Spalte bedeutet, dass das Event zwar gespeichert, im Editor-Reporting aber nicht angezeigt wird.

Event Tag Data Target Display-Text im Editor-Reporting
Klick auf einen Hyperlink kauz.link.open url MESSAGE – die Bot-Nachricht, die den Link enthielt Der*die Chatbotnutzer*in hat auf folgenden Link geklickt: [url]
Ausführen von Action.OpenUrl kauz.adaptivecard.actionurl.open url MESSAGE – die Bot-Nachricht mit der Adaptive Card Der*die Chatbotnutzer*in hat auf folgenden Aktionslink in der Adaptive Card geklickt: [url]
Ausführen von Action.Execute, Verb sendMail kauz.adaptivecard.sendMail.open address MESSAGE – die Bot-Nachricht mit der Adaptive Card Der*die Chatbotnutzer*in hat auf folgenden E-Mail-Aktionslink in der Adaptive Card geklickt: [address]
Absenden der E-Mail aus einer Adaptive Card kauz.adaptivecard.sendMail.send targetMailAddress MESSAGE – die Bot-Nachricht mit der Adaptive Card Der Nutzer hat eine E-Mail an folgenden Empfänger gesendet: [targetMailAddress]
Bewertung einer Antwort kauz.rating.event rating (positive | negative) MESSAGE – die bewertete Bot-Nachricht Der*die Chatbotnutzer*in hat eine Chatbotantwort bewertet: [positiv|negativ]
Bewertung einer Konversation kauz.rating.conversation rating (positive | negative), comment CONVERSATION – die bewertete (aktuelle) Konversation Der*die Chatbotnutzer*in hat die Konversation bewertet: [positiv|negativ]
Ausführen der Aktion set-meta kauz.actions.set-meta (frei) relevante Metadaten MESSAGE – die Bot-Nachricht mit der set-meta-Aktion Die folgenden Metadaten wurden gesetzt: [{"[key^1]":"[value^1]", ...}]
Ausführen der Aktion unset-meta kauz.actions.unset-meta (frei) relevante Metadaten MESSAGE – die Bot-Nachricht mit der unset-meta-Aktion Die folgenden Metadaten wurden entfernt: [{"[key^1]":"[value^1]", ...}]
Wechsel der Chatsprache kauz_chat_i18n_language_change previous_language, current_language CONVERSATION – die aktuelle Konversation –
Anbieten des Livechat-Buttons kauz_livechat_offer – MESSAGE – die Bot-Nachricht mit dem Chat-Link Dem*der Chatbotnutzer*in wurde ein Link zum Livechat angeboten.
Klick auf den Livechat-Button kauz_livechat_click url MESSAGE – die Bot-Nachricht mit dem geklickten Chat-Link Der*die Chatbotnutzer*in hat den Livechat geöffnet: [url]
Ende einer Phonebot-Sitzung nur Phonebot kauz.phonebot.session_end – kein Target Der Bot/Anrufer hat das Gespräch beendet.
Unbekannter Tag (Fallback) (unbekannt) (unbekannt) – [tag] : [data]

# Datenstrukturen je Tag

Target-Typ: MESSAGE

Feld Typ Pflicht Beschreibung
url string ja Die gemeldete URL: geöffneter Link, Aktions-URL der Adaptive Card bzw. Livechat-URL oder Livechat-Aktionsname. 
{
  "url": "https://kauz.ai/"
}

Target-Typ: MESSAGE

Feld Typ Pflicht Beschreibung
address string ja Empfängeradresse des mailto:-Links. Darf eine leere Zeichenkette sein. 
{
  "address": "service@kauz.ai"
}

Target-Typ: MESSAGE

Feld Typ Pflicht Beschreibung
targetMailAddress string nein Adresse, an die die E-Mail gesendet wurde. 
{
  "targetMailAddress": "service@kauz.ai"
}

Target-Typ: MESSAGE

Feld Typ Pflicht Beschreibung
rating string ja Bewertung der Bot-Antwort: positive oder negative. 
{
  "rating": "positive"
}

Target-Typ: CONVERSATION

Feld Typ Pflicht Beschreibung
rating string ja Bewertung der Konversation: positive oder negative.
comment string nein Freitextkommentar, den die*der Nutzer*in zur Bewertung abgegeben hat. 
{
  "rating": "negative",
  "comment": "Meine Frage wurde nicht beantwortet."
}

Target-Typ: MESSAGE

data ist eine freie Zuordnung beliebiger Schlüssel zu String-Werten: die gesetzten bzw. entfernten Metadaten-Einträge.

{
  "warenkorb": "gefuellt",
  "kundenstatus": "bestandskunde"
}

Target-Typ: CONVERSATION

Feld Typ Pflicht Beschreibung
previous_language string ja Sprachcode, der vor dem Wechsel aktiv war. Darf eine leere Zeichenkette sein.
current_language string ja Sprachcode, der nach dem Wechsel aktiv ist. Darf eine leere Zeichenkette sein. 
{
  "previous_language": "de",
  "current_language": "en"
}

Target-Typ: MESSAGE

Dieses Event trägt keine Nutzdaten. data ist immer ein leeres Objekt.

{}

# Antwort

Feld Typ Beschreibung
id string Eindeutige ID des angelegten Events.
chatbot string Name des Chatbots, für den das Event erfasst wurde.
conversationId string ID der Konversation, zu der das Event gehört.
type string Event-Typ, immer Analytics.
date string Zeitpunkt der Erzeugung (ISO 8601).
sender object id der*des Endnutzer*in und type, bei Nutzer-Analytics-Events immer USER.
target object id und type (MESSAGE oder CONVERSATION) des Bezugsobjekts.
tag string Führender Tag des angelegten Events.
data object Die mit dem Event gespeicherten Nutzdaten, wie in der Anfrage gesendet.
meta object Die mit dem Event gespeicherten Metadaten. 
curl --location --request POST "https://example.kauz.ai/partner/v1/events/analytics" \
--header "Authorization: Bearer eyJhbGciOiJSUzI1NiIs..." \
--header "kauz-chatbot: helpdesk" \
--header "Content-Type: application/json" \
--data-raw "{
   \"conversationId\":\"a311a62f-8e01-445a-89e2-186ebf016d55\",
   \"client\":\"mein-frontend\",
   \"senderId\":\"73acad72-7827-4fde-b398-c59607a42826\",
   \"tags\":[\"kauz.link.open\"],
   \"target\":{
      \"id\":\"51a156da-9393-4a0a-af1e-e76d4d5dbfc7\",
      \"type\":\"MESSAGE\"
   },
   \"data\":{
      \"url\":\"https://kauz.ai/\"
   },
   \"meta\":{
      \"referrer\":\"https://example.com/hilfe\"
   }
}"
 
{
  "id": "4098db68-17d9-4216-bf41-4a3e751637f4",
  "chatbot": "helpdesk",
  "conversationId": "a311a62f-8e01-445a-89e2-186ebf016d55",
  "type": "Analytics",
  "date": "2026-07-24T16:22:05.101Z",
  "sender": {
    "id": "73acad72-7827-4fde-b398-c59607a42826",
    "type": "USER"
  },
  "target": {
    "id": "51a156da-9393-4a0a-af1e-e76d4d5dbfc7",
    "type": "MESSAGE"
  },
  "tag": "kauz.link.open",
  "data": {
    "url": "https://kauz.ai/"
  },
  "meta": {
    "referrer": "https://example.com/hilfe"
  }
}

Das zugrundeliegende Datenmodell eines Analytics-Events beschreibt die Dokumentation zum Kauz-Markup.

AnalyticsEvent extends Event
../kauz-markup/#analyticsevent-extends-event