POST/api/public/widget/message
Sendet eine Nachricht des Besuchers an den Chatbot und liefert dessen Antwort – der zentrale Endpunkt des Chat-Widgets.
Senden Sie `widget_code`, `message`, die `visitor_id` und – ab der zweiten Nachricht – die `session_id` aus der vorherigen Antwort. Beim ersten Aufruf einer neuen Konversation lassen Sie `session_id` leer oder setzen sie auf `null`. Die Antwort enthält im Objekt `data` die `session_id`, den Antworttext `response` sowie gegebenenfalls Schaltflächen (`buttons`), Produktvorschläge (`products`) und den Gesprächszustand (`state`). Header `X-Widget-Token` mit dem Embed-Token und `widget_code` sind erforderlich. Fehlt der Token, antwortet der Server mit 401 `WIDGET_TOKEN_MISSING`, ist er ungültig mit 401 `WIDGET_TOKEN_INVALID`; Aufrufe von nicht freigegebenen Domains erhalten 403 `WIDGET_ORIGIN_DENIED`, ein deaktiviertes Widget 404 `WIDGET_DISABLED`. Fehlt die `visitor_id`, antwortet der Server mit 400 `VISITOR_ID_REQUIRED`. Der Aufruf ist nicht idempotent: Jedes Senden erzeugt eine weitere Besuchernachricht und eine weitere Antwort. Sperren Sie die Eingabe, solange eine Anfrage läuft, und wiederholen Sie sie nicht automatisch.
Überblick
Aufruf: POST /api/public/widget/message. Der Endpunkt gehört zur Gruppe „Chat-Widget“ der API von Zentor App. Er erfordert ein gültiges Widget-Embed-Token. Der Aufruf ist nicht idempotent: Jeder erfolgreiche Aufruf löst die Aktion erneut aus. Pflichtparameter: widget_code (Body), message (Body), visitor_id (Body). Optionale Parameter: session_id (Body). Dokumentierte Fehlerfälle: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Die Beispielantwort unten zeigt den Aufbau einer erfolgreichen Antwort im JSON-Format.
Auth & Absicherung
Widget-Embed-Token (Header X-Widget-Token) + Origin-Freigabeliste
Idempotent: Nein
Parameter
widget_code(body, string, erforderlich)— Widget-Code aus Ihrem Einbindungscodemessage(body, string, erforderlich)— Text der Besuchernachrichtvisitor_id(body, string, erforderlich)— Besucher-ID, die das Widget erzeugt und im Browser speichertsession_id(body, string)— Sitzungs-ID aus der vorherigen Antwort; beim ersten Aufruf einer neuen Konversation leer oder `null`Beispiel-Request
{"widget_code":"...","message":"Hallo, was kann Zentor App?","visitor_id":"<UUID oder client-generierte ID>"}Beispiel-Response
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Fehlercodes
401 WIDGET_TOKEN_MISSING — Der Header `X-Widget-Token` fehlt.401 WIDGET_TOKEN_INVALID — Der Embed-Token passt nicht zum Widget-Code.400 VISITOR_ID_REQUIRED — Das Feld `visitor_id` fehlt.Geprüftes Verhalten
Eine gültige Nachricht liefert 200 mit der Antwort des Chatbots; fehlender oder ungültiger Token sowie fehlende `visitor_id` liefern die dokumentierten Fehlercodes.
Chat-Widget
GET /api/public/widget/healthEinfache Erreichbarkeitsprüfung des Widget-Dienstes.GET /api/public/widget/config/:widget_codeLiefert die öffentliche Konfiguration eines Widgets (Anzeigename, Begrüßungstext, Design, Sprache, Sprachfunktion) für die Initialisierung im Browser.GET /api/public/widget/historyLädt den bisherigen Nachrichtenverlauf einer Widget-Konversation, zum Beispiel nach dem Neuladen der Seite.POST /api/public/widget/pollRuft Nachrichten ab, die nach einem Zeitpunkt eingegangen sind – etwa die Antwort eines Mitarbeiters, der das Gespräch übernommen hat.POST /api/public/widget/ratingSpeichert die Bewertung des Besuchers zu einer Konversation (hilfreich oder nicht hilfreich).POST /api/public/widget/trackErfasst ein anonymes Nutzungsereignis des Widgets (z. B. „Widget geöffnet“) für die Auswertungen im Dashboard.POST /api/public/widget/voice-transcribeWandelt eine Sprachaufnahme des Besuchers in Text um (Spracheingabe), sofern die Sprachfunktion für das Widget aktiviert ist.POST /api/public/widget/voice-speakWandelt Text in gesprochene Sprache um (Sprachausgabe im Widget), sofern die Sprachfunktion aktiviert ist.