Schnittstelle: Gespräche und Verwaltung

Q: Was passiert mit den Artikeln, wenn ich die Shopanbindung trenne?

Sie bleiben im Katalog. DELETE /api/v1/catalog/shop entfernt nur die Anbindung; Artikel löschen Sie einzeln mit DELETE /api/v1/catalog/{id}.

Sitzungswege der App für Gespräche, Besuchersperren, Team, Weiterleitung, Katalog, Shop, Auswertung, Vorgänge und Protokoll: Felder, Grenzen, Rollen und Fehler.

In einfacher Sprache

Über diese Wege liest und ändert die Anwendung ihre Daten. Dazu gehören Gespräche und gesperrte Besucher. Auch das Team gehört dazu. Andere Wege gelten für Regeln, wohin ein Fall geht. Weitere Wege gelten für den Katalog, den Shop und die Zahlen. Auch Fälle und das Protokoll sind dabei. Sie brauchen die Marke aus der Anmeldung. Eigene Systeme mit Schlüssel nutzen andere Wege.

Stand 4. Oktober 2026

Alle Themen der Dokumentation

Diese Seite beschreibt die Wege, über die die App selbst Gespräche, Besuchersperren, das Team, Weiterleitungsregeln, Katalog und Shopanbindung, die Auswertung, Vorgänge und das Aktivitätsprotokoll liest und ändert. Alle Wege liegen unter https://app.xicbot.de/api/v1/ und verlangen eine Sitzungsmarke im Kopf Authorization: Bearer …, wie unter Anmeldung beschrieben. Angebundene Systeme mit API-Schlüssel nutzen eigene Wege, siehe Integration.

Zugang, Rollen und Drosseln

Jede Anfrage durchläuft drei Stufen. Zuerst prüft der Server die Sitzungsmarke und ob das Konto aktiv ist. Danach muss die E-Mail-Adresse der angemeldeten Person bestätigt sein; bis dahin antwortet jeder Weg dieser Seite mit 403 und email_unverified, und die App zeigt „Dieser Bereich bleibt gesperrt, bis die E-Mail-Adresse bestätigt ist.“ Zuletzt prüft jeder Weg seine Mindestrolle, manche zusätzlich ein Paketmerkmal und eine benannte Drossel.

Rollen

Rollen sind gestuft: eine höhere Rolle darf, was eine niedrigere darf. Wie Sie Rollen vergeben, steht unter Team und Rollen.

Rolle im Code	Bezeichnung in der App	Wege auf dieser Seite
`viewer`	Lesen	lesende Wege außer dem Aktivitätsprotokoll, eigene Bereitschaft, Einladung annehmen
`editor`	Bearbeiten	Gespräche bearbeiten, anlegen und beschreiben, Weiterleitungsregeln, Katalog, Status von Vorgängen
`admin`	Verwaltung	Gespräche löschen, Aufbewahrungsfristen, Besuchersperren, Team, Shopanbindung, Aktivitätsprotokoll
`owner`	Inhaber	Klartext eines Gesprächs, Ausfuhr im Klartext, Wochenbericht bestellen

Gemeinsame Ablehnungen

Diese Antworten kann fast jeder Weg geben. Der Körper ist JSON mit dem Feld error; das allgemeine Format und die Prüffehler mit 422 beschreibt Grundlagen.

Status	`error`	Bedeutung
`401`	–	Sitzungsmarke fehlt oder gilt nicht mehr, siehe Anmeldung.
`403`	`no_tenant`	Die Person gehört zu keinem Konto.
`403`	`tenant_<Status>`	Das Konto ist nicht aktiv. `message` lautet „Das Konto ist derzeit nicht aktiv.“
`403`	`email_unverified`	Die E-Mail-Adresse ist nicht bestätigt.
`403`	`role_too_low`	Die Rolle reicht nicht; `required` nennt die verlangte Rolle.
`402`	`plan_feature_missing`	Dem Paket fehlt das Merkmal; dazu `feature`, `plan`, `plan_name` und `available_in`.
`402`	`plan_limit_reached`	Eine Zahlgrenze des Pakets ist erreicht; dazu `limit`, `allowed`, `used`, `plan` und `plan_name`.
`503`	`plan_limit_unmeasured`	Der Zähler für eine Zahlgrenze ließ sich nicht lesen; dazu `limit` und `reason`. Der Weg lässt die Anfrage dann nicht durch.
`429`	–	Eine benannte Drossel ist überschritten, siehe Grenzen.
`500`	`not_logged`	Der Eintrag ins Aktivitätsprotokoll kam nicht zustande; die Änderung ist nicht gespeichert. Die App zeigt „Nicht gespeichert: Der Eintrag ins Protokoll kam nicht zustande. Bitte versuchen Sie es erneut.“

Welche Merkmale und Zahlgrenzen Ihr Paket hat, steht unter Pakete und Kontingente und auf der Seite Preise; wie die Paketsperre antwortet, unter Grenzen.

Drosseln

Einige Wege tragen eine benannte Drossel. Gezählt wird je angemeldeter Person, ersatzweise je Herkunft der Anfrage, in einem Fenster von einer Minute.

Drossel	Anfragen je Minute	Wege
`conversations`	30	Ausfuhr als CSV, Gespräch anlegen, Bewertung, Klartext, Anhänge, Bericht der Auswertung
`conversation-send`	20	Nachricht in ein Gespräch senden
`catalog`	20	Artikel anlegen, ändern und einführen; Shopanbindung speichern, prüfen und abgleichen
`invitations`	5	Einladung senden

Gespräche

In der App liegen diese Wege hinter Gespräche und Postfach; was dort zu sehen ist, beschreiben Gespräche und Postfach. Lesen darf jede Rolle, jede Arbeitsaktion an einem Gespräch verlangt mindestens Bearbeiten.

Liste

GET /api/v1/conversations

Liefert eine Seite von Gesprächen, maskiert, gefiltert und sortiert.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Parameter	Werte	Standard	Wirkung
`page`	1 bis 10000	1	Seite
`per_page`	1 bis 200	50	Einträge je Seite
`sort`	`created_at`, `message_count`, `frustration_score`, `status`, `escalated_at`	`created_at`	Sortierspalte; bei Gleichstand entscheidet die Kennung
`dir`	`asc`, `desc`	`desc`	Richtung
`assistant`	Kennung, höchstens 64 Zeichen	–	nur Gespräche dieses Assistenten
`channel`	`test`, `widget`, `api`	–	Herkunft des Gesprächs
`status`	`open`, `closed`, `escalated`	–	Zustand
`language`	`unknown` oder Sprachkürzel wie `de` oder `de-at`	–	`unknown` findet Gespräche, deren Sprache nicht erkannt wurde
`mailbox`	`0`, `1`	–	`1`: übergeben und noch nicht erledigt, die Liste im Postfach
`assigned`	`none`, `me` oder Kennung einer Person, höchstens 64 Zeichen	–	Zuständigkeit; `none` findet Gespräche ohne zuständige Person
`queue`	Name einer Stelle, höchstens 80 Zeichen, oder `none`	–	Stelle aus der Weiterleitung; `none` findet Gespräche ohne Stelle
`unverified`	`0`, `1`	–	`1`: Gespräche mit mindestens einer Antwort, deren Aussage als unbelegt markiert ist
`q`	Suchbegriff, höchstens 120 Zeichen	–	Suche in Titel und Nachrichtentext
`from`, `to`	Datum oder Zeitpunkt	–	Zeitraum nach Anlagezeit; ein Wert ohne Versatz gilt in `zone`; ein bloßes Datum in `to` schließt den ganzen Tag ein
`zone`	Zeitzonenname, höchstens 64 Zeichen	`Europe/Berlin`	Zone, in der `from` und `to` gelesen werden; Tagesgrenzen und der Folgetag eines bloßen Datums werden dort gerechnet. Unbekannt und mit `from` oder `to`: `422` mit `unknown_timezone`

Ein Wert im falschen Typ wird abgelehnt und nicht übergangen; die Antwort ist dann 422. Die Suche findet Teilzeichenfolgen, % und _ gelten wörtlich. Mit der Rolle Inhaber wird im Klartext gesucht, mit jeder anderen Rolle in der maskierten Fassung: gefunden wird nur, was die Rolle auch sehen kann. Findet die Suche in der maskierten Fassung mehr als 20000 Gespräche, antwortet der Weg mit 422, search_too_broad und limit, statt die Liste zu kürzen; grenzen Sie dann Zeitraum oder Filter ein. Wo der Filter protokolliert wird, steht für die Suche nur "q": true, nicht der Suchbegriff.

Feld	Inhalt
`conversations`	Gespräche der Seite, Felder siehe Felder eines Gesprächs
`total`	Zahl aller Treffer
`page`, `per_page`	Seite und Seitengröße
`sort`, `dir`	angewandte Sortierung
`language`	gesetzter Sprachfilter
`languages`	bis zu 50 erkannte Sprachen der Gespräche, alphabetisch
`masked`	`true`: die Liste ist maskiert

Felder eines Gesprächs

Feld	Inhalt
`id`	Kennung
`assistant_id`, `assistant`	Kennung und Name des Assistenten
`channel`	`widget`, `test` oder `api`
`host`	Herkunft beim Widget; bei Test- und Schnittstellengesprächen der Hostname aus `Origin` oder `Referer` der Anfrage, ohne beides `null`
`language`	erkannte Sprache
`title`	Titel, maskiert außer im Klartext
`status`	`open`, `closed` oder `escalated`
`message_count`	Zahl der Nachrichten
`created`, `updated`	Zeitpunkte nach ISO 8601
`frustration_score`	Frustrationswert des Gesprächs
`escalation_reason`, `escalated_at`	Übergabegrund, maskiert, und Zeitpunkt der Übergabe
`assigned_user_id`, `assigned_to`, `assigned_at`	zuständige Person; `assigned_to` ist ihr Name, ersatzweise ihre E-Mail-Adresse
`taken_over_at`	Beginn einer laufenden Übernahme, sonst `null`
`queue`	Stelle aus der Weiterleitung
`resolved_at`	Zeitpunkt der Erledigung
`flagged_at`	Zeitpunkt der Markierung, sonst `null`
`tags`	Schlagworte, ohne Eintrag `[]`
`internal_note`	interne Notiz
`masked`	`true`, solange das Gespräch nicht im Klartext gelesen wird

Einzelansicht, Klartext und Anhänge

GET /api/v1/conversations/{id}

Liefert ein Gespräch mit seinem Verlauf, maskiert. Eine unbekannte Kennung ergibt 404 mit not_found.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Feld	Inhalt
`conversation`	Felder wie unter Felder eines Gesprächs
`messages`	Verlauf aus den jüngsten 500 Nachrichten und den jüngsten 500 Werkzeugaufrufen, ältere fallen am Anfang weg; Texte maskiert; Antworten des Assistenten mit `rating` (`1`, `0` oder `null`)
`masked`	`true` in dieser Ansicht
`masked_kinds`	Arten personenbezogener Angaben, die im Verlauf maskiert wurden
`access_log`	die letzten 20 Klartextzugriffe auf dieses Gespräch (`conversation.revealed`) mit `id`, `time`, `action`, `who` und `reason`
`attachments`	Anhänge mit `id`, `name`, `mime`, `bytes`, `sha256`, `lead_id` und `time`

Bei Werkzeugaufrufen im Verlauf bleiben die Strukturfelder unmaskiert: id, key, kind, state, duration_ms, approval_path, needs_confirmation, chain_capped und created_at; die übrigen Felder laufen durch die Maskierung. Auch die Werte unbelegter Aussagen sind maskiert. Die App sagt dazu „Personenbezogenes ist maskiert: E-Mail, Telefon, IBAN und Anschrift.“

POST /api/v1/conversations/{id}/reveal

Liefert dasselbe Gespräch im Klartext, mit masked: false. Jeder Zugriff wird als conversation.revealed mit Grund protokolliert und erscheint danach in access_log.

Anmeldung: Sitzungsmarke, nur Inhaber
Begrenzung: conversations, 30 je Minute

Feld	Pflicht	Regel	Bedeutung
`reason`	ja	5 bis 200 Zeichen	Grund für den Zugriff; in der App Grund für den Zugriff

Status	`error`	Bedeutung
`403`	`role_too_low`	Rolle ist nicht Inhaber; `required` ist `owner`.
`422`	–	Grund fehlt oder ist zu kurz; die App meldet „Bitte einen Grund mit mindestens fünf Zeichen angeben.“
`404`	`not_found`	Gespräch unbekannt.
`500`	`not_logged`	Kein Protokolleintrag, darum kein Klartext.

GET /api/v1/attachments/{id}

Lädt einen Anhang als Datei herunter. Jeder Abruf wird als attachment.read protokolliert.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: conversations, 30 je Minute

Antwort oder Kopf	Inhalt
`200`	Datei mit `Content-Disposition: attachment`; eine nicht zugelassene Dateiart kommt als `application/octet-stream`
`Content-Security-Policy`	`default-src 'none'; sandbox`
`X-Content-Type-Options`	`nosniff`
`Cache-Control`	`private, no-store, max-age=0`
`Referrer-Policy`	`no-referrer`
`404` `not_found`	Anhang unbekannt
`410` `file_missing`	Der Eintrag besteht, die Datei fehlt; dazu `measured: false`

Ausfuhr als CSV

Beide Ausfuhren setzen das Paketmerkmal für den Gesprächsexport voraus und tragen die Drossel conversations. Fehlt das Merkmal in Ihrem Paket, antworten sie mit 402 plan_feature_missing; feature ist dann conversation_export. Ohne reveal=1 sind die Inhalte maskiert. Mit reveal=1 braucht es die Rolle Inhaber und einen Grund. Jede Ausfuhr wird als conversation.exported protokolliert, mit Klartextangabe, Grund, Zeilenzahl und Filter; kommt der Eintrag nicht zustande, bricht nur die Ausfuhr im Klartext mit 500 und not_logged ab; die maskierte Ausfuhr läuft ohne Eintrag weiter.

GET /api/v1/conversations/export

Führt die gefilterten Gespräche als CSV aus, eine Zeile je Gespräch mit den Spalten id, created_at, assistant, channel, language, status, messages, title und escalation. Es gelten die Filter der Liste. In der App heißt das Gefilterte Gespräche als CSV.

Anmeldung: Sitzungsmarke, jede Rolle; Klartext nur Inhaber
Begrenzung: conversations, 30 je Minute

Parameter	Werte	Bedeutung
Filter der Liste	wie oben	grenzen die Ausfuhr ein
`reveal`	`0`, `1`	`1` fordert Klartext an
`reason`	höchstens 200 Zeichen, mit `reveal=1` mindestens 5	Grund der Klartext-Ausfuhr

Antwort	Inhalt
`content-type`	`text/csv; charset=utf-8`
`content-disposition`	Download mit dem Namen `conversations.csv`
`x-rows`	Zahl der Zeilen
`x-masked`	`1` maskiert, `0` Klartext
Körper	Spalten durch Semikolon getrennt, Zeilenende CRLF
`422` `too_many`	mehr als 5000 Treffer; dazu `total` und `limit`. Die App meldet „Zu viele Gespräche für einen Export. Bitte den Zeitraum eingrenzen.“
`422` `reason_required`	`reveal=1` ohne Grund von mindestens 5 Zeichen; dazu `min`
`403` `role_too_low`	`reveal=1` ohne die Rolle Inhaber
`402` `plan_feature_missing`	Ihr Paket enthält den Gesprächsexport nicht; dazu `feature`, `plan`, `plan_name` und `available_in`

GET /api/v1/conversations/{id}/export

Führt den Verlauf eines Gesprächs als CSV aus, eine Zeile je Nachricht oder Werkzeugaufruf, mit den Spalten time, role, text, state, rating, tool_key und tool_state. Der Dateiname ist gespraech-<Kennung>.csv.

Anmeldung: Sitzungsmarke, jede Rolle; Klartext nur Inhaber
Begrenzung: conversations, 30 je Minute

Antwort	Inhalt
`x-rows`	Zahl der Zeilen
`x-capped`	`1`, wenn der Verlauf bei 500 Nachrichten oder 500 Werkzeugaufrufen abgeschnitten wurde, sonst `0`
`404` `not_found`	Gespräch unbekannt
weitere	`402` `plan_feature_missing`, `reveal`, `reason` und ihre Fehler wie bei der Ausfuhr der Liste

Gespräche bearbeiten

Alle Wege dieses Abschnitts verlangen mindestens Bearbeiten. Eine unbekannte Gesprächskennung ergibt 404 mit not_found. Wenn nicht anders genannt, antworten sie mit dem Gespräch in den Feldern eines Gesprächs.

POST /api/v1/conversations/{id}/escalate

Übergibt ein Gespräch von Hand an das Team: status wird escalated, escalated_at wird gesetzt, eine frühere Erledigung wird aufgehoben. Der Grund wird an einen vorhandenen Übergabegrund angehängt, zusammen höchstens 300 Zeichen; ohne Grund steht dort „Von Hand übergeben“. Auch diese Übergabe durchläuft die Weiterleitungsregeln. Ist das Gespräch schon übergeben, bleibt es unverändert, auch sein Grund, und die Regeln laufen nicht erneut. Die Antwort enthält in beiden Fällen conversation und unchanged (true, wenn nichts geändert wurde).

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`reason`	nein	höchstens 200 Zeichen	Übergabegrund

POST /api/v1/conversations/{id}/assign

Setzt die zuständige Person. user_id: null oder eine leere Zeichenkette hebt die Zuständigkeit auf. Eine Kennung, die nicht zum Konto gehört, ergibt 422 mit unknown_user. In der App heißen die Schaltflächen Übernehmen und Freigeben.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`user_id`	nein	Kennung, höchstens 64 Zeichen, oder `null`	zuständige Person

POST /api/v1/conversations/{id}/takeover

Übernimmt ein Widget-Gespräch und macht Sie zur zuständigen Person; ein schon gesetztes assigned_at bleibt. Solange die Übernahme läuft, antwortet der Assistent nicht; Ihre Nachrichten gehen als Nachrichten des Teams an den Besucher. Die App nennt das Gespräch übernehmen und zeigt danach „Sie führen dieses Gespräch. Der Assistent antwortet nicht.“ Ein wiederholter Aufruf ändert die Zeitpunkte nicht. 409 kommt nur, solange eine andere Person aus dem Konto die Übernahme führt; eine Zuständigkeit ohne Übernahme geht auf Sie über. Die Übernahme einer Person, die nicht mehr zum Konto gehört, gilt als frei und geht mit neuem Zeitpunkt auf Sie über.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Status	`error`	Bedeutung
`422`	`not_live`	Das Gespräch kommt nicht aus dem Widget.
`403`	`consent_revoked`	Der Besucher hat seine Einwilligung zurückgezogen, siehe Einwilligung und Besucherrechte.
`409`	`taken_over_by_other`	Eine andere Person führt die Übernahme; `assigned_to` nennt sie.

POST /api/v1/conversations/{id}/release

Beendet die Übernahme; taken_over_at wird null, die Zuständigkeit bleibt. In der App heißt das Übernahme beenden. Ein Gespräch ohne Übernahme zurückzugeben ist kein Fehler. Führt eine andere Person aus dem Konto die Übernahme, antwortet der Weg mit 409 und taken_over_by_other; die Übernahme einer Person, die nicht mehr zum Konto gehört, lässt sich beenden.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

POST /api/v1/conversations/{id}/resolve

Markiert das Gespräch als erledigt: status wird closed, resolved_at wird gesetzt, eine eigene Übernahme endet (taken_over_at wird null), und der Webhook conversation.ended wird ausgelöst. Ein schon geschlossenes Gespräch bleibt unverändert, samt erstem resolved_at, und löst kein zweites Ereignis aus; die Antwort trägt dann unchanged: true. Führt eine andere Person aus dem Konto das Gespräch, folgt 409 mit taken_over_by_other und assigned_to. In der App heißt das Als erledigt markieren.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

POST /api/v1/conversations/{id}/mark

Setzt Markierung, Schlagworte und interne Notiz. Geändert wird nur, was im Körper steht. In der App heißen die Felder Markieren, Schlagworte und Interne Notiz.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`flagged`	nein	wahr oder falsch	`true` setzt `flagged_at`, eine vorhandene Markierung behält ihren Zeitpunkt; `false` löscht ihn
`tags`	nein	Liste mit höchstens 10 Einträgen zu je höchstens 40 Zeichen	Leerzeichen am Rand und doppelte Einträge fallen weg; eine leere Liste entfernt alle Schlagworte
`note`	nein	höchstens 2000 Zeichen	interne Notiz; leer entfernt sie

POST /api/v1/conversations/{id}/messages/{message}/rating

Bewertet eine Antwort des Assistenten: 1 Hilfreich, 0 Nicht hilfreich, null hebt die Bewertung auf (Noch nicht bewertet). Die Antwort enthält message mit id und rating.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: conversations, 30 je Minute

Status	`error`	Bedeutung
`422`	–	`rating` fehlt im Körper oder ist nicht `0`, `1` oder `null`.
`404`	`not_found`	Nachricht gehört nicht zu diesem Gespräch.
`422`	`not_rateable`	Die Nachricht stammt nicht vom Assistenten.

POST /api/v1/conversations/{id}/tool/{call}/confirm

Bestätigt einen vorgeschlagenen Werkzeugaufruf, der auf Freigabe wartet. Die Antwort enthält call und duplicate. Ist der Aufruf nicht mehr im Zustand proposed oder kam ein zweiter Klick zuvor, kommt derselbe Stand mit duplicate: true zurück statt eines Fehlers. Ein unbekannter Aufruf ergibt 404 mit not_found. Werkzeuge beschreibt Werkzeuge.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

POST /api/v1/conversations/{id}/tool/{call}/reject

Verwirft einen vorgeschlagenen Werkzeugaufruf. Antwort und Verhalten bei einem zweiten Klick wie beim Bestätigen; ein unbekannter Aufruf ergibt 404 mit not_found.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Anlegen, schreiben und löschen

POST /api/v1/conversations

Legt ein Testgespräch an, mit channel test und status open. Die Antwort 201 enthält conversation und greeting, die Begrüßung der aktiven Version. Wozu Testgespräche dienen, steht unter Probieren und abnehmen.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: conversations, 30 je Minute

Feld	Pflicht	Regel	Bedeutung
`assistant_id`	ja	Kennung, höchstens 64 Zeichen	Assistent des Gesprächs

Status	`error`	Bedeutung
`404`	`not_found`	Assistent unbekannt.
`422`	`no_version`	Der Assistent hat keine aktive Version.

POST /api/v1/conversations/{id}/send

Schreibt eine Nachricht in ein Gespräch. Läuft eine Übernahme, wird der Text als Nachricht des Teams gespeichert (role operator) und die Antwort ist 201 mit message (id, role, text, author, state, time). Sonst antwortet der Assistent, und die Antwort kommt als Ereignisstrom wie unter Integration beschrieben.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: conversation-send, 20 je Minute

Feld	Pflicht	Regel	Bedeutung
`text`	ja	1 bis 4000 Zeichen	Nachricht

Status	`error`	Bedeutung
`409`	`taken_over_by_other`	Eine andere Person führt die Übernahme; `assigned_to` nennt sie.
`409`	`not_taken_over`	Widget-Gespräch ohne Übernahme: in ein laufendes Besuchergespräch schreibt nur, wer es übernommen hat.
`422`	`no_version`	Assistent oder Version des Gesprächs gibt es nicht mehr.
`409`	`reply_in_progress`	Zu diesem Gespräch läuft schon eine Antwort.

DELETE /api/v1/conversations/{id}

Löscht ein Gespräch und protokolliert das als conversation.deleted. Die Antwort ist {"deleted": true}. Ohne Protokolleintrag bleibt das Gespräch bestehen; dann kommt 500 mit not_logged. Fristen und Löschwege beschreibt Aufbewahrung und Löschung.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Aufbewahrungsfristen

GET /api/v1/conversations/retention

Liefert die Fristen in Tagen: retention mit general, test und api sowie default_general, den Startwert für neue Konten (90).

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

PUT /api/v1/conversations/retention

Setzt die drei Fristen und antwortet in derselben Form wie der lesende Weg. Die Änderung wird als retention.updated protokolliert. In der App heißen die Felder Alle Gespräche, Testgespräche und Über die Schnittstelle; dort steht auch „Die Fristen ändern kann, wer die Rolle Verwaltung oder Inhaber hat.“

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`general`	ja, darf `null` sein	1 bis 3650	Frist für alle Gespräche; `null` heißt: keine Frist gesetzt
`test`	ja, darf `null` sein	1 bis 3650	Testgespräche; `null` folgt der allgemeinen Frist
`api`	ja, darf `null` sein	1 bis 3650	Gespräche über die Schnittstelle; `null` folgt der allgemeinen Frist

Besuchersperren

Eine Sperre weist künftige Widget-Gespräche eines Besuchers ab, entweder nach seiner Adresse (address) oder nach seiner Sitzung (session). Ausgangspunkt ist ein Gespräch; die Sperre speichert einen Streuwert der Adresse oder Sitzung aus diesem Gespräch. Wie Gespräche in der App gesperrt werden, steht unter Gespräche.

GET /api/v1/visitor-blocks

Liefert in data die letzten 200 Sperren, neueste zuerst.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

POST /api/v1/visitor-blocks

Legt eine Sperre an und protokolliert sie als visitor.blocked. Gibt es für dieselbe Art und denselben Streuwert schon eine Sperre, wird sie aktualisiert: Grund und Dauer werden überschrieben, der Trefferzähler bleibt. Die Antwort ist 201 mit der Sperre in data. Ohne Protokolleintrag wird die Sperre weder angelegt noch geändert; dann kommt 500 mit not_logged.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`conversation_id`	ja	UUID	Gespräch, aus dem gesperrt wird
`kind`	ja	`address`, `session`	Art der Sperre
`reason`	ja	8 bis 200 Zeichen	Grund
`days`	nein	1 bis 3650	Dauer in Tagen; ohne Angabe unbefristet

Status	`error`	Bedeutung
`404`	`not_found`	Gespräch unbekannt.
`422`	`no_address`	Zum Gespräch ist kein Wert für die gewählte Art gespeichert.
`500`	`not_logged`	Kein Protokolleintrag, keine Sperre.

DELETE /api/v1/visitor-blocks/{id}

Hebt eine Sperre auf, protokolliert als visitor.unblocked. Die Antwort ist {"ok": true}; eine unbekannte Sperre ergibt 404 mit not_found.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Feld	Inhalt
`id`, `kind`, `reason`	Kennung, Art und Grund
`expires_at`	Ende der Sperre oder `null` für unbefristet
`active`	ob die Sperre gerade greift
`hits`, `last_hit_at`	abgewiesene Versuche und der letzte davon
`created_at`, `created_by`	Anlage und Name der Person, die gesperrt hat
`conversation_id`, `host`	Ausgangsgespräch und seine Herkunft

Team

Diese Wege stehen in der App hinter Team. Rollen und Einladungen aus Sicht der Oberfläche beschreibt Team und Rollen.

GET /api/v1/team

Liefert Mitglieder, offene Einladungen und den Stand der Sitzplätze. Gezeigt werden höchstens 200 Personen, nach E-Mail-Adresse sortiert; ist die Liste abgeschnitten, zeigt die App „Es werden die ersten {n} Personen gezeigt.“

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Feld	Inhalt
`members`	Personen mit `id`, `name`, `email`, `role`, `available` und `available_at`
`total`, `capped`	Zahl aller Personen und ob die Liste abgeschnitten ist
`invitations`	offene Einladungen mit `id`, `email`, `role`, `expires_at` und `created_at`
`seats`	Sitzplätze mit `limit`, `used`, `measured`, `reason` und `exceeded`; ist der Zähler nicht lesbar, steht `measured: false` mit `reason: no_counter`

POST /api/v1/availability

Schaltet die eigene Bereitschaft. available_at wird beim Einschalten gesetzt, wenn es noch leer ist, und beim Ausschalten gelöscht. Die Antwort enthält member. In der App heißt das Bereitschaft einschalten und Bereitschaft beenden, mit dem Hinweis „Wer bereit ist, erscheint im Postfach als verfügbar für eine Übergabe.“ Solange Ihre E-Mail-Adresse nicht bestätigt ist, steht dort statt der Schaltfläche „Die Bereitschaft lässt sich einschalten, sobald Ihre E-Mail-Adresse bestätigt ist.“

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`available`	ja	wahr oder falsch	bereit oder nicht

POST /api/v1/team/invitations

Lädt eine Person ein. Die Einladung gilt 168 Stunden, also sieben Tage, und geht per E-Mail mit einem Link zur Seite Einladung annehmen in der Sprache der einladenden Person hinaus. Scheitert der Versand, bleibt die Einladung trotzdem angelegt. Protokolliert als team.invited; die Antwort ist 201 mit invitation. In der App: Person einladen, Schaltfläche Einladung senden.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: invitations, 5 je Minute

Feld	Pflicht	Regel	Bedeutung
`email`	ja	gültige Adresse, höchstens 190 Zeichen	Adresse der eingeladenen Person
`role`	ja	`viewer`, `editor`, `admin`	Rolle nach dem Annehmen; Inhaber wird so nicht vergeben

Status	`error`	Bedeutung
`422`	`validation`	`fields.email` enthält `validation.already_member` (schon im Team) oder `validation.invitation_open` (Einladung läuft noch).
`403`	`role_too_low`	Die eigene Rolle liegt unter der vergebenen.
`402`	`plan_limit_reached`	Alle Sitzplätze sind belegt. Die App meldet „Alle Sitzplätze sind belegt. Nehmen Sie eine Einladung zurück oder erweitern Sie das Paket.“

DELETE /api/v1/team/invitations/{id}

Nimmt eine offene Einladung zurück; sie wird als zurückgenommen markiert, nicht gelöscht. Protokolliert als team.invitation_revoked, Antwort {"revoked": true}. Unbekannte oder nicht mehr offene Einladungen ergeben 404 mit not_found. In der App: Zurücknehmen.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

PATCH /api/v1/team/members/{id}

Ändert die Rolle einer Person auf viewer, editor oder admin. Protokolliert als team.role_changed; die Antwort enthält member.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Status	`error`	Bedeutung
`404`	`not_found`	Person gehört nicht zum Konto.
`422`	`not_self`	Eigene Rolle; die App meldet „Die eigene Rolle lässt sich hier nicht ändern.“
`422`	`owner_protected`	Der Inhaber; die App meldet „Der Inhaber lässt sich nicht ändern oder entfernen.“
`403`	`role_too_low`	Die eigene Rolle reicht für diese Änderung nicht.

DELETE /api/v1/team/members/{id}

Entfernt eine Person aus dem Team und protokolliert das als team.member_removed. Arbeitet sie gerade in diesem Konto, werden ihre Sitzungsmarken gelöscht; gehört sie dann zu keinem weiteren Konto, wird ihr Zugang gelöscht, sonst wechselt sie in das älteste verbleibende Konto, das nicht gelöscht ist. Arbeitet sie gerade in einem anderen Konto, bleiben ihre Sitzungen dort bestehen. Antwort {"removed": true}; not_self und owner_protected wie beim Ändern. In der App: Entfernen, mit der Rückfrage „Diese Person aus dem Team entfernen? Laufende Sitzungen enden sofort.“

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

POST /api/v1/team/invitations/accept

Nimmt eine Einladung mit der angemeldeten Person an. Protokolliert als team.invitation_accepted; die Antwort enthält joined: true, tenant mit id und name sowie role. Die App zeigt danach „Sie gehören jetzt zum Team.“

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`token`	ja	höchstens 120 Zeichen	Marke aus dem Einladungslink

Status	`error`	Bedeutung
`422`	`invalid_token`	Marke unbekannt, abgelaufen oder zurückgenommen; die App meldet „Diese Einladung ist abgelaufen oder wurde zurückgenommen. Bitten Sie um eine neue.“
`403`	`wrong_account`	Die angemeldete E-Mail-Adresse ist nicht die eingeladene. Verglichen wird die vereinheitlichte Form beider Adressen, etwa ohne Zusatz hinter einem Plus.

Weiterleitungsregeln

Bei jeder Übergabe, auch von Hand, prüft der Server die aktiven Regeln in ihrer Reihenfolge; es gewinnt die erste passende. Verglichen wird im Übergabegrund und im Gesprächstitel, in Kleinschreibung und ohne Wortgrenze: das Stichwort rechnung trifft auch „Rechnungsadresse“. Die Regel setzt die Stelle (queue) und, wenn noch niemand zuständig ist, ihre Person; gehört diese nicht mehr zum Konto, bleibt es bei der Stelle. Hat das Gespräch schon eine Stelle, bleibt sie. Passt keine Regel, bleibt die Stelle leer.

In der App heißt der Bereich Weiterleitung, die Felder Stelle und Stichwörter (mehrere mit Komma getrennt). Ohne Regel zeigt sie „Keine Regel. Ohne Regel bleibt jede Übergabe ohne Stelle.“ Wie Stellen im Postfach erscheinen, steht dort.

GET /api/v1/routing-rules

Liefert rules in ihrer Reihenfolge und max, die Höchstzahl von 50 Regeln.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

POST /api/v1/routing-rules

Legt eine Regel am Ende der Liste an; ohne is_active ist sie aktiv. Die Antwort ist 201 mit rule und der ganzen Liste in rules.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`queue`	ja	höchstens 80 Zeichen	Name der Stelle
`keywords`	ja	1 bis 20 Einträge zu je höchstens 60 Zeichen	Stichwörter
`assigned_user_id`	nein	Kennung, höchstens 64 Zeichen	Person, die zuständig wird
`is_active`	nein	wahr oder falsch	ob die Regel geprüft wird

Status	`error`	Bedeutung
`422`	`unknown_user`	Die Person gehört nicht zum Konto.
`422`	`too_many_rules`	Es gibt schon 50 Regeln.

PUT /api/v1/routing-rules/{id}

Ändert Stelle, Stichwörter, Person und Aktivschalter einer Regel mit denselben Feldern wie beim Anlegen. Fehlt is_active, wird die Regel wieder aktiv. Die Position ändert sich dabei nicht. Die Antwort enthält rule und die Liste in rules. Eine unbekannte Regel ergibt hier wie beim Verschieben und Löschen 404 mit not_found.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

POST /api/v1/routing-rules/{id}/up

Schiebt eine Regel um eine Stelle nach oben. Die Position vergibt der Server. Die Antwort enthält moved, false bei der obersten Regel, und die Liste in rules.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

DELETE /api/v1/routing-rules/{id}

Löscht eine Regel. Die Antwort enthält deleted: true und die verbleibende Liste in rules.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

Feld	Inhalt
`id`, `position`	Kennung und Platz in der Reihenfolge
`queue`, `keywords`	Stelle und Stichwörter
`assigned_user_id`, `assigned_to`	Person und ihr Name
`is_active`	aktiv oder nicht

Katalog und Shopanbindung

Alle Wege dieses Abschnitts setzen das Paketmerkmal für die Shopanbindung voraus; fehlt es, antworten sie mit 402 und plan_feature_missing. In der App liegt das unter Katalog, beschrieben unter Katalog und Shop.

Artikel

GET /api/v1/catalog

Liefert eine Seite von Artikeln, nach Titel sortiert, in products, dazu total, page und per_page. total zählt alle Artikel des Kontos, auch wenn search gesetzt ist.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Parameter	Werte	Standard	Wirkung
`search`	höchstens 120 Zeichen	–	Titel oder Shop-Kennung beginnt mit dem Begriff
`page`	ab 1	1	Seite
`per_page`	1 bis 200	50	Einträge je Seite

POST /api/v1/catalog

Legt einen Artikel an. Die Antwort ist 201 mit product. Ist die Shop-Kennung schon vergeben, kommt 422 mit identifier_taken.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: catalog, 20 je Minute

Feld	Pflicht	Regel	Bedeutung
`external_id`	ja	höchstens 100 Zeichen	Kennung im Shop
`title`	ja	höchstens 200 Zeichen	Titel
`description`	nein	höchstens 800 Zeichen	Beschreibung
`price_cents`, `list_price_cents`	nein	ganze Zahl, 0 bis 100000000	Preis und Streichpreis in Cent; der Streichpreis wird nicht gegen den Preis geprüft
`currency`	nein	genau drei Zeichen	Währung, in Großbuchstaben gespeichert; ohne Angabe `EUR`
`image_url`, `product_url`, `cart_url`	nein	Adresse, höchstens 500 Zeichen	Bild, Artikelseite und Warenkorb-Link
`is_available`	nein	wahr oder falsch	lieferbar; ohne Angabe `true`
`attributes`	nein	Objekt	freie Merkmale; ohne Angabe bleibt der bisherige Wert
`rating_tenths`	nein	0 bis 50	Bewertung in Zehnteln, 50 ist die volle Bewertung; ausgegeben wird zusätzlich `rating` als Zehntel geteilt durch zehn
`rating_count`	nein	0 bis 100000000	Zahl der Bewertungen
`delivery_days`	nein	0 bis 365	Lieferzeit in Tagen
`features`	nein	höchstens 6 Einträge zu je höchstens 60 Zeichen	Merkmale für die Produktkarte
`action`	nein	`none`, `product`, `cart`	Schaltfläche der Produktkarte; ohne Angabe `product`
`accessories`, `also_bought`	nein	je höchstens 6 Shop-Kennungen zu höchstens 100 Zeichen	Zubehör und häufig zusammen gekaufte Artikel

Ein Artikel wird mit den Feldern der Produktkarte ausgegeben (id, external_id, title, description, price_cents, currency, price_text, list_price_cents, list_price_text, saving_cents, saving_percent, image_url, product_url, is_available, rating, rating_count, delivery_days, features, action, action_url), ergänzt um attributes, action_setting, rating_tenths, cart_url, accessories, also_bought und updated_at.

PUT /api/v1/catalog/{id}

Ändert einen Artikel mit denselben Feldern wie beim Anlegen, außer external_id, die sich nicht ändern lässt. Der Weg schreibt den Artikel neu: ein weggelassenes Feld fällt auf seinen Standard oder null zurück, nur attributes bleibt ohne Angabe erhalten. Antwort mit product; ein unbekannter Artikel ergibt 404 mit not_found.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: catalog, 20 je Minute

DELETE /api/v1/catalog/{id}

Löscht einen Artikel. Die Antwort ist {"deleted": true}.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

POST /api/v1/catalog/import

Führt bis zu 500 Artikel in einem Aufruf ein, in einer Transaktion. Abgeglichen wird über external_id: ein zweiter Lauf mit denselben Kennungen legt keine Dubletten an, sondern ändert die vorhandenen Artikel. Die Antwort enthält new, changed und total.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: catalog, 20 je Minute

Feld	Pflicht	Regel	Bedeutung
`products`	ja	1 bis 500 Einträge	Artikel mit den Feldern wie beim Anlegen

Shopanbindung

Die Anbindung liest nur: im Shop wird über sie nichts angelegt, geändert oder bestellt. Der Zugriffsschlüssel geht einmal hinein; jede Antwort zeigt von ihm nur die letzten vier Zeichen in access_key_masked. Lesen, Speichern und Abgleich antworten mit connection, einem Objekt mit den Feldern der folgenden Tabelle.

Feld	Inhalt
`base_url`	Adresse des Shops
`access_key_masked`	Endung des Schlüssels mit vorangestellter Auslassung
`currency`, `is_active`	Währung und ob die Anbindung aktiv ist
`sync_pending`, `sync_started_at`, `sync_requested_at`	offener Abgleich, sein Start und seine Anforderung
`last_sync_at`, `last_sync_ok`, `last_sync_error`, `last_success_at`	letzter Abgleich, sein Ergebnis, sein Fehler und der letzte erfolgreiche
`counts`	Zahlen des letzten Abgleichs oder `null`

GET /api/v1/catalog/shop

Liefert die Anbindung des Kontos in connection; ist keine gespeichert, ist connection null.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

PUT /api/v1/catalog/shop

Speichert die Anbindung. Die Adresse wird geprüft, bevor sie eingetragen wird, denn der Server ruft sie später selbst mit dem Schlüssel ab. Zeigt eine geänderte Adresse auf einen anderen Shop, braucht es einen neuen Schlüssel. is_active ändert sich nur, wenn es mitgeschickt wird. Die Antwort enthält connection.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: catalog, 20 je Minute

Feld	Pflicht	Regel	Bedeutung
`base_url`	ja	höchstens 300 Zeichen, `https`	Adresse des Shops, zum Beispiel `https://shop.example.com`
`access_key`	beim ersten Speichern und bei neuem Shop	12 bis 200 Zeichen aus Buchstaben, Ziffern, `_` und `-`	Zugriffsschlüssel
`is_active`	nein	wahr oder falsch	Anbindung aktiv

Status	`error`	Bedeutung
`422`	`url_unreadable`	Adresse nicht lesbar.
`422`	`https_required`, `scheme_not_allowed`	Die Adresse nutzt kein `https`.
`422`	`name_unresolvable`	Der Name lässt sich nicht auflösen.
`422`	`target_not_allowed`	Die Adresse zeigt nicht ins öffentliche Netz.
`422`	`access_key_required`	Neuer Shop ohne neuen Schlüssel.

POST /api/v1/catalog/shop/test

Prüft die gespeicherte Anbindung mit einem Probeabruf. Erfolg: ok: true mit currency und has_products. Misserfolg: ok: false mit error, etwa key_unreadable oder einem Grund wie beim Speichern. Höchstens drei Prüfungen je Minute; danach 429 mit too_many_tests, retry_after und dem Kopf Retry-After. Ohne Anbindung: 404 mit connection_missing.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: catalog, 20 je Minute

POST /api/v1/catalog/shop/sync

Fordert einen Abgleich an, der als Hintergrundauftrag läuft (siehe Hintergrundaufträge). Die Antwort ist 202 mit job_id, already_pending und connection; ein zweiter Klick bekommt den offenen Auftrag zurück, mit already_pending: true. Ist kein Auftrag mehr offen, nimmt der Weg eine neue Anforderung frühestens 900 Sekunden nach der letzten an; davor kommt 429 mit sync_too_soon, retry_after, connection und dem Kopf Retry-After.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: catalog, 20 je Minute

Status	`error`	Bedeutung
`404`	`connection_missing`	Keine Anbindung gespeichert.
`422`	`connection_inactive`	Anbindung ist abgeschaltet.

DELETE /api/v1/catalog/shop

Trennt die Anbindung. Die Artikel bleiben im Katalog. Die Antwort ist {"deleted": true}; ohne gespeicherte Anbindung kommt 404 mit connection_missing.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Auswertung

Die folgenden Wege bis einschließlich GET /api/v1/analytics/report setzen das Paketmerkmal für die Gesprächsauswertung voraus; fehlt es, antworten sie mit 402 und plan_feature_missing. Lesen darf dort jede Rolle. In der App ist das Auswertung, beschrieben unter Auswertung. Testgespräche mit channel test, also die aus dem Probierdialog und die Prüfgespräche der Abnahme, zählen in diesen Zahlen nicht mit, wie in der App.

Parameter	Werte	Standard	Wirkung
`period`	`7d`, `30d`, `90d`	`30d`	Zeitraum in Tagen; der laufende Tag zählt mit
`zone`	Zeitzonenname, höchstens 64 Zeichen	`Europe/Berlin`	Zone, in der Tage gerechnet werden. Ältere Namen, die Browser noch melden, etwa `Asia/Calcutta` oder `Europe/Kiev`, nimmt der Weg an und rechnet unter dem heutigen Namen (`Asia/Kolkata`, `Europe/Kyiv`); diesen Namen nennen auch Antworten mit `zone`. Groß- und Kleinschreibung spielen keine Rolle, `zone` nennt die übliche Schreibung. Die festen Versätze `Etc/GMT+1` bis `Etc/GMT+12` und `Etc/GMT-1` bis `Etc/GMT-14` gelten mit dem Vorzeichen der Zeitzonendatenbank: `Etc/GMT+1` liegt eine Stunde hinter UTC. Eine unbekannte Zone ergibt `422` mit `unknown_timezone`, ebenso ein Versatz wie `+01:00`. Die Seite Auswertung zeigt dann „Die Zeitzone dieses Geräts erkennt der Dienst nicht. Die Zahlen lassen sich darum keinem Tag zuordnen und werden nicht angezeigt.“
`assistant`	UUID	–	nur dieser Assistent; ein unbekannter ergibt `404` mit `unknown_assistant`

GET /api/v1/analytics

Liefert die 32 Kennzahlenkarten des Zeitraums in einem Abruf: period, zone, from, to, days, assistant und cards.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Jede Karte hat value, measured und reason. value ist null, wenn measured false ist; reason nennt dann den Grund. Anteile tragen value in Prozent mit einer Nachkommastelle und dazu counter und denominator. coverage ist ein Mittelwert in Prozent und trägt nur denominator; messages_per_conversation, reply_ms_p50 und reply_ms_p95 tragen keins von beiden.

Gruppe	Karten
Umfang	`conversations`, `messages`, `answered`, `messages_per_conversation`
Übergabe und Frust	`escalations`, `escalation_rate`, `self_resolved`, `frustration_rate`
Antwortgüte	`abstentions`, `unanswered`, `citation_rate`, `coverage`
Wissenssuche, aus dem jüngsten Prüflauf im Zeitraum, für das ganze Konto unabhängig von `assistant`	`retrieval_mrr`, `retrieval_hit_rate`
Regeln und Sperren	`enforcement_rate`, `hard_topic_rate`, `blocked_rate`
Tempo und Verbrauch	`reply_ms_p50`, `reply_ms_p95`, `units`
Werkzeuge	`tool_calls`, `tool_executed`, `tool_rejected`, `tool_errors`
Vorgänge	`leads`, `appointments`, `carts`, `abandoned`, `abandon_rate`
Besucherbewertung, gezählt nach Zeitpunkt der Bewertung	`visitor_ratings`, `visitor_helpful_rate`, `visitor_rating_coverage`

`reason`	Bedeutung
`no_conversation`	kein Gespräch im Zeitraum
`no_reply`	keine Antwort, aus der sich der Wert rechnen ließe
`no_search`	keine Wissenssuche
`no_probe`	kein Prüflauf im Zeitraum
`no_enforcement_check`	keine Regelprüfung
`no_tool_call`	kein Werkzeugaufruf
`no_rating`	keine Bewertung

GET /api/v1/analytics/timeseries

Zeitreihe je Tag in der gewählten Zone. days enthält je Tag day, conversations, messages und escalations sowie citation_rate, unanswered, escalation_rate, coverage und retrieval_mrr in der Form der Kennzahlkarten; dazu kommen period, zone und measured.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/topics

Die häufigsten Themen, höchstens 15. Jedes Thema trägt previous, seine Zahl im gleich langen Zeitraum unmittelbar davor, und direction (up, down oder flat); gab es davor kein Thema, nennt previous den Grund no_previous_question und direction ist null. Ohne Besucherfrage im Zeitraum ist measured false mit reason no_question, ohne erkennbares Thema mit no_topic.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/distribution

Verteilung der Gespräche nach Sprache (languages) und nach Fensterbreite (viewports: handy, tablet, desktop, breit), jede Gruppe mit eigenem measured. Jeder Eintrag in entries hat key, conversations und share; der Anteil bezieht sich auf basis, die Gespräche mit Angabe. Gespräche ohne Angabe zählen getrennt unter without. Ohne Gespräch im Zeitraum steht reason auf no_conversation; fehlt in einer Gruppe jede Angabe, auf no_language oder no_viewport.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/unanswered

Fragen, auf die der Assistent keine Antwort hatte: zu den jüngsten 50 Ausweichantworten (fallback) je die Besucherfrage davor, maskiert und auf 300 Zeichen gekürzt. questions enthält je Frage conversation_id, question und when, dazu kommt clusters.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/gaps

Erkannte Wissenslücken, höchstens 50. Anders als bei unanswered zählt hier auch eine ausdrückliche Ablehnung getrennt von einer Antwort ohne Beleg. Ist der Fragetext nicht mehr vorhanden, bleibt die Lücke gezählt, question ist dann null und question_available false. Jede Lücke hat kind (refused oder uncited); refused, uncited und total zählen alle Lücken des Zeitraums.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/blocks

Die Sperrfälle des Zeitraums, höchstens 50: was abgewiesen wurde und wo eine Grenze gegriffen hat, aufgeschlüsselt je Thema. Jeder Fall in cases hat kind (blocked oder enforced), topics, hard und when; topics zählt je Thema, dazu kommen checked, enforced, hard, blocked und total.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/dropoffs

Abbruchstellen und Zielereignisse mit ihrer Stelle im Gespräch; die Stelle ist die laufende Nummer der Nachricht, die erste Nachricht ist Stelle 1. Als Abbruch zählt ein offenes, nicht übergebenes Gespräch mit mindestens einer Besuchernachricht, in dem seit 30 Minuten (minutes) keine Nachricht mehr kam und zu dem es weder Anfrage noch Termin noch Warenkorb gibt. Die Antwort enthält dropoffs, positions, goals mit kind lead, appointment oder cart, total und goals_total. Die Verteilung geht über alle Fälle des Zeitraums, die Liste über die jüngsten 50; total nennt die volle Zahl.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/recommendations

Je Auffälligkeit des Zeitraums ein Vorschlag mit der Zahl und dem Bereich, den er betrifft. Eine Aussage über die Wirkung einer Änderung enthält er nicht. Jeder Eintrag in recommendations hat kind, count und target (wissen, assistenten oder werkzeuge); aufgeführt sind nur Arten mit mindestens einem Fall, die häufigste zuerst. kinds nennt die Zahl der möglichen Arten, total die der aufgeführten.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/versions

Die veröffentlichten Versionen eines Assistenten, höchste Nummer zuerst, höchstens 50. Die Antwort enthält assistant, versions mit id, number und published_at, dazu count und capped; Zeitraum und Zone wirken hier nicht. Ohne assistant antwortet der Weg mit 422 und assistant_required.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/comparison

Vergleicht ein Zeitfenster vor der Veröffentlichung einer Version mit einem ebenso langen danach, gerechnet über die Zeit und den Assistenten der Version. Das Fenster danach endet spätestens zum Zeitpunkt der Anfrage; ist es dadurch kürzer, steht in after partial: true. Die Antwort enthält version, comparable, before, after und delta; delta nennt je Karte die Differenz und direction (up, down oder flat), keine Wirkung. Fehlt einer Seite der Messwert, steht bei der Karte side_not_measured. Ist die Version nicht veröffentlicht, ist comparable false mit reason not_published; liegt die Veröffentlichung in der Zukunft, mit no_window. Der Parameter version (UUID) ist Pflicht; eine unbekannte Version ergibt 404 mit unknown_version.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/analytics/report

Stellt einen Bericht aus Kennzahlen, Zeitreihe, Themen, unbeantworteten Fragen, Lücken, Sperrfällen und Abbrüchen zusammen (metrics, timeseries, topics, unanswered, gaps, blocks, dropoffs) mit dem Zeitpunkt in created. Der Bericht wird frisch gerechnet, nicht aus dem Zwischenspeicher.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: conversations, 30 je Minute

GET /api/v1/analytics/subscription

Zeigt den Wochenbericht: weekly_report (ohne Einstellung true), period 7d, day monday und recipient, die E-Mail-Adresse des Inhabers, wenn sie bestätigt ist, sonst null.

Anmeldung: Sitzungsmarke
Begrenzung: keine benannte Drossel

PUT /api/v1/analytics/subscription

Bestellt den Wochenbericht oder bestellt ihn ab. Nur der Inhaber schaltet ihn, weil die Mail an ihn geht. Protokolliert als report.subscription.updated, Antwort in derselben Form wie der lesende Weg. Ohne Protokolleintrag bleibt die Einstellung unverändert; dann kommt 500 mit not_logged.

Anmeldung: Sitzungsmarke, nur Inhaber
Begrenzung: keine benannte Drossel

Feld	Pflicht	Regel	Bedeutung
`weekly_report`	ja	wahr oder falsch	Wochenbericht an oder aus

Vorgänge

Vorgänge sind Anfragen (leads), Termine (appointments) und Warenkörbe (carts). In der App liegen sie unter Vorgänge, beschrieben unter Termine und Vorgänge. Den Status von Terminen und Warenkörben ändern setzt das Paketmerkmal für Termine und Anfragen voraus; fehlt es, antwortet dieser Weg mit 402 und plan_feature_missing. Lesen und Löschen gehen in jedem Paket.

GET /api/v1/records

Zählt Vorgänge in zwei Gruppen: pending mit den offenen, also leads (neu), appointments (angefragt) und carts (offen), und total mit allen, gegliedert nach denselben drei Arten. plan_locked nennt die Arten ohne Paketmerkmal, deren Status sich nicht ändern lässt; gezählt werden auch sie. available_from nennt das Paket, ab dem alle gesperrten Arten enthalten sind, available_from_name seinen Namen; beide stehen auf null, wenn nichts gesperrt ist oder sich kein solches Paket nennen lässt.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

GET /api/v1/records/{type}

Liefert eine Seite einer Art, neueste zuerst, mit entries, total, page und per_page. Eine unbekannte Art ergibt 404 mit unknown_kind.

Anmeldung: Sitzungsmarke, jede Rolle
Begrenzung: keine benannte Drossel

Parameter	Werte	Standard	Wirkung
`type`	`leads`, `appointments`, `carts`	–	Art im Pfad
`status`	höchstens 20 Zeichen	–	nur dieser Zustand
`page`	ab 1	1	Seite
`per_page`	1 bis 200	50	Einträge je Seite

POST /api/v1/records/{type}/{id}/status

Setzt den Zustand eines Vorgangs. Die Antwort enthält entry. Wird ein Termin auf confirmed gesetzt, löst das den Webhook appointment.confirmed mit id und starts_at aus, und die Antwort enthält zusätzlich confirmation_mail. Ein unbekannter Vorgang ergibt 404 mit not_found. Wird ein abgesagter Termin auf requested oder confirmed gesetzt und ist sein Zeitpunkt inzwischen vergeben, ergibt das 409 mit appointment_slot_taken. Ist beim Setzen eines Termins auf requested oder confirmed die Terminsperre des Kontos belegt, ergibt das 503 mit appointment_lock_busy und Retry-After: 1. In beiden Fällen bleibt der Termin unverändert.

Anmeldung: Sitzungsmarke, ab Bearbeiten
Begrenzung: keine benannte Drossel

DELETE /api/v1/records/{type}/{id}

Löscht einen einzelnen Vorgang, etwa wenn ein Besucher die Löschung seiner Angaben verlangt, und protokolliert das vorher als record.deleted mit Art, Kennung und Zahlen, ohne Name, E-Mail-Adresse oder Telefon. Ohne Protokolleintrag bleibt der Vorgang bestehen; dann kommt 500 mit not_logged. Eine Paketschranke gibt es hier nicht: Termine und Warenkörbe lassen sich auch ohne die Termin-Funktionen löschen. Mit dem Vorgang gehen noch nicht zugestellte Meldungen an angeschlossene Systeme über ihn (lead.created, appointment.requested, appointment.confirmed) und bei einem Termin noch nicht versandte Erinnerungen und Bestätigungen; deren Zeile im Zustellprotokoll steht danach auf failed. Anhänge des Besuchers bleiben beim Gespräch. Mit with_conversation=1 geht das Gespräch, aus dem der Vorgang stammt, mit allen Nachrichten und Anhängen mit. Die Antwort enthält deleted, kind, id, conversation_deleted und counts. Eine unbekannte Art ergibt 404 mit unknown_kind, ein unbekannter Vorgang 404 mit not_found.

Anmeldung: Sitzungsmarke, ab Verwaltung, nicht aus einer Übernahme
Begrenzung: 5 je Minute und Nutzer, gemeinsam für Export, Fristen, Widerspruch und Löschung

Art	Zustände	Felder zusätzlich zu `id`, `conversation_id`, `status`, `created_at`
`leads`	`new`, `seen`, `done`	`name`, `email`, `phone`, `subject`, `source`, `fields`
`appointments`	`requested`, `confirmed`, `cancelled`	`type`, `starts_at`, `duration_min`, `name`, `email`, `phone`, `subject`
`carts`	`open`, `claimed`, `expired`	`items`, `subtotal_cents`, `discount_cents`, `coupon_code`, `shipping_cents`, `total_cents`, `currency`, `pickup_token_set` (nur ob eine Abholmarke gesetzt ist, nicht die Marke)

`confirmation_mail`	Bedeutung
`queued`	Bestätigung an den Besucher eingereiht
`unchanged`	Termin war schon bestätigt, keine neue Mail
`superseded`	Termin ist inzwischen nicht mehr bestätigt
`no_email`	keine E-Mail-Adresse am Termin
`past`	Termin hat schon begonnen, es geht keine Zusage hinaus
`duplicate`	Bestätigung für diesen Beginn gibt es schon
`failed`	Einreihen fehlgeschlagen

Aktivitätsprotokoll

GET /api/v1/activity

Liefert das Aktivitätsprotokoll, 25 Einträge je Seite, neueste zuerst. In der App ist das Protokoll; bei Einträgen mit who_kind api_key zeigt es unter Wer API-Schlüssel „{name}“ mit dem Namen aus who.

Anmeldung: Sitzungsmarke, ab Verwaltung
Begrenzung: keine benannte Drossel

Parameter	Werte	Wirkung
`action`	höchstens 80 Zeichen	nur diese Aktion
`page`	1 bis 1000	Seite

Feld	Inhalt
`entries`	Einträge mit `id`, `time`, `action`, `who`, `who_kind`, `subject_type`, `subject_id` und `data`. `who` ist die E-Mail-Adresse der Person, mit `who_kind` `user`. Hält ein Eintrag in `data.api_key` den auslösenden API-Schlüssel fest, etwa beim Anlegen einer Wissensquelle über die Schnittstelle, steht dort dessen Name zum Zeitpunkt der Handlung, ersatzweise sein `prefix`, mit `who_kind` `api_key`. Sonst sind beide `null`.
`actions`	die Aktionen, die im Protokoll vorkommen, für einen Filter
`total`, `page`, `pages`	Zahl der Einträge, Seite und Seitenzahl

Die Wege dieser Seite schreiben unter anderem conversation.revealed, conversation.exported, conversation.deleted, attachment.read, retention.updated, visitor.blocked, visitor.unblocked, team.invited, team.invitation_revoked, team.role_changed, team.member_removed, team.invitation_accepted, routing.rule_created, routing.rule_updated, routing.rule_moved, routing.rule_deleted und report.subscription.updated.

Häufige Fragen

Warum sind Texte in der Gesprächsliste maskiert?

Liste und Einzelansicht maskieren E-Mail-Adressen, Rufnummern, IBAN und Anschriften, die Ausfuhr ebenso, solange sie nicht mit reveal=1 angefordert wird. Den Klartext eines Gesprächs holt nur der Inhaber über POST /api/v1/conversations/{id}/reveal, mit einem Grund von mindestens fünf Zeichen; der Zugriff wird protokolliert.

Was bedeutet search_too_broad bei der Suche?

Ohne Klartextrecht wird in der maskierten Fassung gesucht. Findet die Suche dort mehr als 20000 Gespräche, bricht der Weg mit 422 ab. Setzen Sie from und to oder weitere Filter, dann suchen Sie erneut.

Warum zeigt die Auswertung nach einer Änderung noch den alten Stand?

Die Wege der Auswertung halten ihre Antwort 60 Sekunden vor. Nach Ablauf rechnet der nächste Abruf neu. Frisch gerechnet wird der Bericht unter GET /api/v1/analytics/report.

Warum kann ich nicht in ein Widget-Gespräch schreiben?

In ein laufendes Besuchergespräch schreibt nur, wer es übernommen hat. Rufen Sie zuerst POST /api/v1/conversations/{id}/takeover auf; ohne Übernahme antwortet der Sendeweg mit 409 und not_taken_over.

Was passiert mit den Artikeln, wenn ich die Shopanbindung trenne?

Sie bleiben im Katalog. DELETE /api/v1/catalog/shop entfernt nur die Anbindung; Artikel löschen Sie einzeln mit DELETE /api/v1/catalog/{id}.

Selbst fragen, Assistent dieser Website

Automatischer Assistent

Einstellungen