Schnittstelle: Widget-Wege

Das Chatfenster spricht mit dem Dienst über 14 Wege unter https://app.xicbot.de/api/v1/public/widget/{key}. Eine Anmeldung brauchen sie nicht: Der Widget-Schlüssel im Pfad bestimmt den Assistenten, und die Gesprächskennung, die der Start eines Gesprächs zurückgibt, bindet jeden weiteren Aufruf an dieses Gespräch. Diese Seite beschreibt jeden Weg mit Anfragefeldern, Antwort und Fehlern. Wie das Chatfenster die Wege nutzt, zeigt Gespräch im Widget; die Wege außerhalb des Widgets stehen unter Öffentliche Wege.

Überblick

Die Pfade in der Tabelle folgen auf https://app.xicbot.de/api/v1/public/widget/{key}. Adresse, Fehlerformat und die Regeln für Aufrufe aus dem Browser beschreibt Grundlagen der Schnittstelle, die Zähler der Drosseln Grenzen der Schnittstelle.

Gemeinsame Regeln

Schlüssel im Pfad

Der Schlüssel {key} ist der Wert des Attributs data-xicbot im Einbaucode: 16 Zufallsbytes, geschrieben als 32 Zeichen aus 0 bis 9 und a bis f. Er ist kein Geheimnis, denn er steht im Quelltext jeder Seite mit dem Widget. Vor jedem Weg prüft der Dienst den Schlüssel und antwortet sonst so:

Einen neuen Schlüssel erzeugt POST /api/v1/assistants/{id}/key mit der Rolle admin, siehe Anmeldung an der Schnittstelle. Der Dienst protokolliert den Wechsel zuerst. Gelingt das nicht, antwortet er mit 500 und not_logged, und der bisherige Schlüssel bleibt stehen. Sonst steht der neue Wert in key, und der alte Schlüssel ergibt ab dann unknown_widget. Tauschen Sie deshalb den Einbaucode auf allen Seiten, siehe Öffentlicher Schlüssel.

Drosseln und Deckel

Zwei Schichten begrenzen die Wege. Die benannte Drossel zählt je Besucher, gebildet aus der IP-Adresse des Besuchers (bei IPv6 den ersten 64 Bit) und dem Widget-Schlüssel: widget erlaubt 60 und widget-send 12 Aufrufe je Minute, siehe Grenzen je Besucher. Dahinter prüft der Dienst die Deckel des Widgets, deren Werte am Konto hängen.

• Der Deckel für Aufrufe gilt für Einstellungen, Start, Verlauf, Widerruf, Bewertung, Auskunft, Löschen, für Bestätigen, Ablehnen und Rückmelden eines Werkzeugaufrufs sowie für Hochladen, Auflisten und Abrufen von Anhängen. Die Vorgabe sind 60 Aufrufe je Minute und 2000 je Tag.
• Der Deckel für Fragen gilt nur für POST send. Die Vorgabe sind 10 Fragen je Minute und 200 je Tag.
• Jeder Deckel zählt auf dem Besucher und, wenn der Aufruf ein Gespräch nennt, zusätzlich auf diesem Gespräch. Das Gespräch kommt aus dem Pfad oder aus conversation_id im Rumpf. Jeder der beiden Zähler kann abweisen; gezählt wird erst, wenn keiner abgewiesen hat.
• Die Zeitfenster sind 60 Sekunden und 86.400 Sekunden. Ein Deckel unter 1 ist abgeschaltet.

Weist ein Deckel ab, lautet die Antwort 429 mit diesem Rumpf und dem Kopf Retry-After:

Gesprächskennung

Der Start eines Gesprächs gibt conversation_id zurück, eine UUID. POST send und jeder Weg mit {conversation} im Pfad suchen das Gespräch über diese Kennung, den Assistenten des Schlüssels und den Kanal widget. Passt eines davon nicht, lautet die Antwort 404 mit not_found. Ein Gespräch eines anderen Assistenten oder aus einem anderen Kanal ist über das Widget also nicht erreichbar. Die Kennungen von Nachrichten, Werkzeugaufrufen und Anhängen sind ebenfalls UUIDs und werden nur innerhalb des genannten Gesprächs gesucht.

Aufrufe aus dem Browser

Die CORS-Regeln unter /api/v1/public/ lassen die Herkunft null zu. Das Chatfenster läuft in einem Rahmen mit sandbox="allow-scripts" ohne allow-same-origin, und ein solcher Rahmen sendet Origin: null. Welche Seiten ein Gespräch beginnen dürfen, entscheidet nicht CORS, sondern die Domainliste beim Start eines Gesprächs. Methoden, Köpfe und die Gültigkeit der Vorabfrage stehen unter Schnittstelle: Grundlagen.

Fehler

Fehler kommen als JSON mit einem Code in error; einige Wege legen weitere Felder dazu, die Tabellen unten nennen sie. Die Prüfung der Anfragefelder antwortet mit 422, einem Text in message und je Feld einer Liste in errors, siehe Fehlerformat. Werten Sie den Code aus, nicht den Text. Hat der Antwortstrom von POST send einmal begonnen, meldet er Fehler als Ereignis und nicht mehr als Status.

Einstellungen abrufen

Mit host und ohne preview merkt sich der Dienst Zeitpunkt und Rechnernamen der Einbindung, für denselben Rechnernamen höchstens alle 300 Sekunden. Gegen die Domainliste prüft dieser Weg host nicht; das geschieht erst beim Start eines Gesprächs.

language wirkt nur auf die Texte, die der Dienst selbst stellt: note, limit_notice und den Standardtext der Einwilligung. Begrüßung und Ansprache bleiben, wie sie im Assistenten stehen. Ohne gültigen Wunsch gilt en, wenn die aktive Fassung des Assistenten englisch ist, sonst de.

Die Antwort ist ein JSON-Objekt mit diesen Feldern:

Der Standardtext der Einwilligung lautet „Ich bin damit einverstanden, dass mein Gespräch gespeichert und zur Beantwortung meiner Frage verarbeitet wird.“ Die Grenzen der Anhänge stehen in der Antwort, damit das Chatfenster eine zu große Datei ablehnen kann, bevor sie hochgeladen wird.

forms enthält höchstens 10 Einträge, geordnet nach dem Schlüssel des Werkzeugs: nur aktive Werkzeuge zum Ausfüllen von Formularen, die die öffentliche Rolle nutzen darf. Werte stehen darin keine; das Chatfenster trägt nur in die genannten Felder ein. Einrichtung unter Formulare vorausfüllen, die Regeln für outreach_rules unter Ansprache.

Gespräch beginnen

Der Dienst prüft in dieser Reihenfolge und bricht beim ersten Treffer ab:

1. 1

   Schritt 1

   Felder prüfen

   Ungültige Felder ergeben 422 mit message und errors.

2. 2

   Schritt 2

   Aktive Fassung

   Hat der Assistent keine aktive Fassung, lautet die Antwort 422 mit no_version.

3. 3

   Schritt 3

   Deckel für Aufrufe

   Ist der Deckel erreicht, folgt 429 mit too_many_requests.

4. 4

   Schritt 4

   Domainliste

   Passt host nicht zur Domainliste, lautet die Antwort 403 mit host_not_allowed.

5. 5

   Schritt 5

   Sperrliste

   Ist die IP-Adresse des Besuchers gesperrt, folgt 403 mit blocked.

6. 6

   Schritt 6

   Einwilligung

   Verlangt der Assistent eine Einwilligung und fehlt consent: true, lautet die Antwort 422 mit consent_missing. Passt ein mitgeschickter consent_text zu keinem geltenden Einwilligungstext, folgt 422 mit consent_changed; consent_text trägt dann den geltenden Text in der Sprache, die language wählt. Diese Prüfungen stehen vor dem Anlegen: Ohne die nötige Einwilligung legt der Dienst kein Gespräch an.

7. 7

   Schritt 7

   Anlegen

   Erst jetzt legt der Dienst das Gespräch mit dem Status open an und antwortet mit 201.

Ist die Domainliste des Assistenten leer, darf jede Seite ein Gespräch beginnen. Enthält sie Einträge, muss host angegeben sein und entweder einem Eintrag gleichen oder auf einen Punkt und einen Eintrag enden: Der Eintrag example.com deckt shop.example.com mit ab. Einträge trennt ein Komma oder ein Zeilenumbruch, verglichen wird in Kleinbuchstaben. Die Liste pflegen Sie unter Erlaubte Domains.

Gesperrte Besucher legen kein Gespräch mehr an; die Sperre greift, bevor ein Gespräch angelegt wird. Wie Sie Besucher sperren, steht unter Besucher sperren.

Verlangt der Assistent eine Einwilligung, speichert das Gespräch den Zeitpunkt in consent_at und einen Prüfwert in consent_hash. Der Prüfwert ist ein SHA-256 über den Einwilligungstext, den der Besucher in der gewählten Sprache sieht, die Fassung der Datenschutzhinweise und den Rechnernamen. Das ist der eigene Text des Assistenten, sonst der Standardtext der Sprache. Schicken Sie den gezeigten Wortlaut in consent_text mit, gilt die Sprache, deren Text er entspricht. Fehlt er, wählt language die Sprache wie beim Abruf der Einstellungen; ohne gültigen Wunsch gilt en, wenn die aktive Fassung englisch ist, sonst de. Senden Sie in diesem Fall denselben Wunsch wie beim Abruf der Einstellungen: Gilt der Standardtext, hielte der Prüfwert sonst den Wortlaut einer anderen Sprache fest als den angezeigten. Die Einwilligung hängt damit am Gespräch und nicht an einem Wert im Browser. Mehr unter Einwilligung.

Nach dem Anlegen löst der Dienst den Webhook conversation.started mit conversation_id, assistant_id und channel aus.

Frage senden

Hat das Konto einen kleineren Längendeckel als 4000 Zeichen, gilt dieser. Die Frage wird gespeichert, bevor der Strom beginnt. Steht das Gespräch auf closed, öffnet die gespeicherte Frage es wieder: war es übergeben (escalated_at gesetzt), wird es escalated mit neuem escalated_at, sonst open; resolved_at wird leer. Ein Ereignis geht dabei nicht hinaus, und eine abgewiesene Frage öffnet nichts. Je Gespräch läuft höchstens eine Antwort; der Dienst belegt das Gespräch mit einer bedingten Aktualisierung. Endet ein Lauf nicht sauber, gibt die Belegung das Gespräch nach 180 Sekunden frei.

curl -N https://app.xicbot.de/api/v1/public/widget/0123456789abcdef0123456789abcdef/send \
  -H 'Content-Type: application/json' \
  -H 'Accept: text/event-stream' \
  -d '{"conversation_id":"9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d","text":"Ich habe eine Frage zu meiner Bestellung."}'

Ereignisstrom

Nach den Prüfungen antwortet der Weg mit Status 200, Content-Type: text/event-stream; charset=utf-8 und Cache-Control: no-cache, no-store. Jedes Ereignis besteht aus einer Zeile event: mit dem Namen, einer Zeile data: mit einem JSON-Objekt und einer Leerzeile. Umlaute und Schrägstriche stehen unmaskiert im JSON. Das Chatfenster sendet dazu Accept: text/event-stream. Wie es die Ereignisse darstellt, beschreibt Antwortstrom.

citations, contact_offer, follow_ups, handoff mit assistant, redaction, verification und enforcement kommen nur, wenn die Antwort regulär zu Ende läuft. Ein gekürzter Strom sieht so aus:

event: start
data: {"conversation_id":"9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d","question_id":null}

event: text
data: {"t":"Gern helfe ich Ihnen "}

event: text
data: {"t":"bei Ihrer Bestellung."}

event: verification
data: {"state":"no_claims","claims":[],"total":0}

event: enforcement
data: {"state":"clear","topics":[],"handover":false}

event: end
data: {"state":"done","message_id":"4b8e2f10-6c3d-4a5e-9f7b-2d1c0e9a8b76","refused":false,"citations":[]}

Sonderfälle

Die Frage ist in jedem dieser Fälle gespeichert, bevor der Strom beginnt.

• Übernahme: Hat ein Mitarbeiter das Gespräch übernommen, folgen auf start nur live und end mit state gleich live und message_id gleich null. Die Antwort schreibt der Mitarbeiter, siehe Gespräch übernehmen.
• Kontingent erschöpft: Es folgen error mit code gleich quota_exhausted, scope gleich month und retry_after in Sekunden bis zum Monatswechsel, dann die Notfallantwort als text und end mit blocked. Der Status bleibt 200; eine 429 für das Kontingent gibt es nur im Kanal der Integrationsschnittstelle. Siehe Kontingent erschöpft.
• Gesprächsdeckel: Hat der Besucher in diesem Gespräch schon so viele Fragen gestellt, wie der Deckel des Kontos erlaubt, folgen error mit conversation_limit und limit, ein Hinweis als text, handoff mit conversation_limit und end mit blocked. Die Vorgabe sind 60 Fragen, der Wert 0 schaltet den Deckel ab.
• Störung: Bei einer vorübergehenden Störung kann model_switch kommen, und die Antwort läuft weiter. Scheitert sie, folgen fallback, die Notfallantwort als text und end mit fallback.
• Widerruf während des Laufs: Bei Gesprächen mit Einwilligung prüft der Lauf höchstens einmal je Sekunde und noch einmal am Ende, ob die Einwilligung widerrufen wurde. Dann verwirft er die Antwort und sendet revoked sowie end mit revoked.
• Antwort aus einem Frage-Antwort-Paar: Trifft die Frage ein aktives Paar, wird kein Modell gefragt. Auf start folgen die Antwort des Paares in einem einzigen text, citations mit genau einem Beleg (die Frage des Paares als document, chunk_id aus qa: und der Kennung des Paares) und enforcement; berührt die Frage ein gesperrtes Thema oder ein Tabu, können redaction mit notice, ein Hinweis als weiteres text und handoff folgen. Zum Schluss kommt end mit done. verification, follow_ups und contact_offer gibt es dabei nicht. Siehe Frage-Antwort-Paare.
• Nachbearbeitung: redaction ersetzt den gezeigten Text. Mit claims stehen an Stelle unbelegter Aussagen die Platzhalter [nicht belegt] oder [not backed], mit notice hat die Themenprüfung den Text umgeschrieben. Nach enforcement kann ein Hinweis als weiteres text folgen, ebenso ein Hinweis auf unbelegte Aussagen, wenn der Assistent nur aus seinem Wissen antworten darf.

message_id ist die Kennung der gespeicherten Antwort; mit ihr bewerten Sie die Antwort. Wurde nichts gespeichert, ist der Wert null. refused ist nur bei done true, wenn der Assistent die Frage abgelehnt hat. citations nennt die Quellen des Laufs.

Verlauf laden

Die Antwort enthält messages und taken_over. messages besteht aus den jüngsten 50 Nachrichten und den jüngsten 50 Werkzeugaufrufen, gemeinsam aufsteigend nach Zeit sortiert. taken_over ist true, solange ein Mitarbeiter das Gespräch übernommen hat. Ist das Gespräch unbekannt, lautet die Antwort 404 mit not_found.

Einwilligung widerrufen

Die Antwort lautet {"revoked": true, "run_aborted": …}. run_aborted ist true, wenn das Gespräch in diesem Moment für eine Antwort belegt war; ein laufender Lauf verwirft die Antwort dann und endet mit revoked. Der Widerruf wird einmal gesetzt: Ein zweiter Aufruf antwortet gleich und ändert den Zeitpunkt nicht. Mehr unter Widerruf.

Widerruf, Auskunft und Löschen stehen auch gesperrten Besuchern offen; die Sperrliste prüft der Dienst nur beim Start, beim Senden und beim Hochladen eines Anhangs.

Antwort bewerten

Der Deckel wird vor den Feldern geprüft. Mit der Note speichert der Dienst den Zeitpunkt; null löscht beides. Wie das Chatfenster die Knöpfe zeigt, steht unter Bewertung.

Auskunft

Zeitpunkte stehen im Format ISO 8601. Mehr zu den Rechten des Besuchers unter Auskunft.

Gespräch löschen

Die Löschung wird zuerst protokolliert: Der Protokolleintrag mit dem Auslöser visitor und den Anzahlen entsteht in derselben Datenbanktransaktion wie das Löschen und vor ihm. Kommt kein Eintrag zustande, löscht der Dienst nichts und antwortet mit 500 und not_logged. Was mit dem Gespräch zusammen gelöscht wird, beschreibt Was mit dem Gespräch geht.

Werkzeugaufrufe

Schlägt der Assistent einen Schritt vor, der etwas verändert, oder ruft er ein lesendes Werkzeug mit der Freigabe mit Bestätigung auf, kommt im Strom ein Ereignis tool mit state gleich proposed und needs_confirmation gleich true. Ausgeführt wird der Schritt erst, wenn der Besucher ihn bestätigt: Der Bestätigungsweg ist der einzige, auf dem ein veränderndes Werkzeug im Widget läuft; der Antwortlauf selbst führt nur Lesendes aus. Die Karten im Chatfenster beschreibt Werkzeugkarten, die Werkzeuge selbst Werkzeuge.

Ereignis, Verlauf, Auskunft und die Wege dieses Abschnitts zeigen einen Aufruf in derselben Kurzform:

Dauer und Freigabeweg eines Aufrufs gibt das Widget nicht heraus, im Ergebnis auch nicht die Felder note und email_notified. Je Antwort laufen höchstens 5 Werkzeugaufrufe; ein weiterer endet mit failed und chain_capped gleich true.

Aufruf bestätigen

Zuerst setzt der Dienst einen Vorschlag, der älter als 60 Minuten ist, auf expired. Dann setzt er den Aufruf mit einer bedingten Aktualisierung von proposed auf confirmed; von zwei gleichzeitigen Klicks gewinnt nur einer. Beim Klick prüft er erneut, ob das Werkzeug noch besteht, ob Rolle und Paket es erlauben und ob die Pflichtfelder gefüllt sind; sonst endet der Aufruf mit failed. Die Ausführung endet mit executed, timeout oder failed.

duplicate ist true, wenn der Aufruf schon entschieden war oder ein anderer Klick gewonnen hat; der Schritt läuft dann kein zweites Mal. call zeigt in jedem Fall den aktuellen Stand, auch expired.

Aufruf ablehnen

Rückmeldung zur Formularhilfe

Der Rumpf ist JSON. Ohne JSON-Kopf liest der Dienst den rohen Rumpf bis 16384 Byte und wertet ihn als JSON aus; so kann das Ladeskript die Meldung als text/plain mit keepalive schicken. Eine solche Anfrage braucht keine Vorabprüfung und übersteht das Verlassen der Seite, etwa wenn das Formular die Seite beim Absenden wechselt.

Die Meldung ist eine Angabe der Seite des Kunden. Behalten werden nur Feldnamen, die in der Anweisung dieses Aufrufs stehen. Gespeichert wird report mit filled, missing, blocked, submitted und form_found; submitted ist nur true, wenn die Anweisung das Absenden vorsah und abgesendet gleich true ist. Angenommen wird die erste Meldung je Aufruf; jede weitere erhält duplicate gleich true und den schon gespeicherten Bericht. Was die Formularhilfe einträgt, beschreibt Formulare vorausfüllen.

Anhänge

Besucher können Bilder und PDF-Dateien an ein Gespräch hängen, wenn der Assistent das erlaubt; eingeschaltet wird das unter Dateien vom Besucher. Wie der Besucher das im Widget erlebt, steht unter Anhänge im Gespräch. Alle drei Wege zählen neben der benannten Drossel gegen den Deckel für Aufrufe.

Die Art bestimmt der Dienst am Inhalt der Datei, nicht an Endung oder Angabe des Browsers: PNG, JPEG, WebP und PDF werden an ihren ersten Bytes erkannt, alles andere wird abgewiesen. Auch die Größe misst er an der empfangenen Datei.

Anhang hochladen

Vom Dateinamen entfernt der Dienst Schrägstriche, umgekehrte Schrägstriche, Anführungszeichen und Steuerzeichen, behält nur den letzten Pfadteil und kürzt auf 120 Zeichen. Bleibt nichts übrig, heißt die Datei anhang.png, anhang.jpg, anhang.webp oder anhang.pdf.

Gibt es im Gespräch schon eine Anfrage, hängt der Anhang sofort an der jüngsten; lead_id trägt dann ihre Kennung. Entsteht die Anfrage erst später, übernimmt sie alle Anhänge des Gesprächs, deren lead_id noch leer ist. Das Hochladen wird in der Regel im Aktivitätsprotokoll mit Art und Größe festgehalten; kommt dieser Eintrag nicht zustande, bleibt der Anhang trotzdem gespeichert und die Antwort ist 201.

Die Prüfungen laufen in der Reihenfolge der Tabelle; die erste, die greift, bestimmt die Antwort. Die vier Abweisungen aus der Prüfung der Datei (upload_failed, too_large, too_many und type_not_allowed) tragen zusätzlich max_bytes, types und max_per_conversation, damit das Widget dem Besucher die Grenzen nennen kann.

curl -X POST \
  https://app.xicbot.de/api/v1/public/widget/0123456789abcdef0123456789abcdef/conversation/9d1f6c2a-3b4e-4f5a-8c7d-1e2f3a4b5c6d/attachment \
  -F 'file=@schaden.jpg'

Anhänge auflisten

Anhang abrufen

Häufige Fragen