POST/api/public/widget/message
Sends a visitor's message to the chatbot and returns its reply – the central endpoint of the chat widget.
Send `widget_code`, `message`, the `visitor_id` and – from the second message on – the `session_id` from the previous response. On the first call of a new conversation, leave `session_id` empty or set it to `null`. In the `data` object, the response contains the `session_id`, the reply text `response` and, where applicable, buttons (`buttons`), product suggestions (`products`) and the conversation state (`state`). The `X-Widget-Token` header with the embed token and `widget_code` are required. If the token is missing, the server responds with 401 `WIDGET_TOKEN_MISSING`, if it is invalid with 401 `WIDGET_TOKEN_INVALID`; calls from domains that are not approved receive 403 `WIDGET_ORIGIN_DENIED`, a deactivated widget 404 `WIDGET_DISABLED`. If the `visitor_id` is missing, the server responds with 400 `VISITOR_ID_REQUIRED`. The call is not idempotent: every send creates another visitor message and another reply. Lock the input while a request is pending and do not retry it automatically.
Overview
Call: POST /api/public/widget/message. This endpoint belongs to the “Chat Widget” group of the Zentor App API. It requires a valid widget embed token. The call is not idempotent: every successful call triggers the action again. Required parameters: widget_code (body), message (body), visitor_id (body). Optional parameters: session_id (body). Documented error cases: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. The example response below shows the structure of a successful JSON response.
Auth & Security
Widget embed token (X-Widget-Token header) + origin allowlist
Idempotent: No
Parameters
widget_code(body, string, required)— Widget code from your embed codemessage(body, string, required)— Text of the visitor's messagevisitor_id(body, string, required)— Visitor ID generated by the widget and stored in the browsersession_id(body, string)— Session ID from the previous response; empty or `null` on the first call of a new conversationExample Request
{"widget_code":"...","message":"Hello, what can Zentor App do?","visitor_id":"<UUID or client-generated ID>"}Example Response
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Error Codes
401 WIDGET_TOKEN_MISSING — The `X-Widget-Token` header is missing.401 WIDGET_TOKEN_INVALID — The embed token does not match the widget code.400 VISITOR_ID_REQUIRED — The `visitor_id` field is missing.Verified behaviour
A valid message returns 200 with the chatbot's reply; a missing or invalid token and a missing `visitor_id` return the documented error codes.
Chat Widget
GET /api/public/widget/healthSimple availability check of the widget service.GET /api/public/widget/config/:widget_codeReturns the public configuration of a widget (display name, greeting, design, language, voice feature) for initialisation in the browser.GET /api/public/widget/historyLoads the message history of a widget conversation, for example after the page has been reloaded.POST /api/public/widget/pollFetches messages received after a given point in time – for example the reply of an agent who has taken over the conversation.POST /api/public/widget/ratingStores the visitor's rating of a conversation (helpful or not helpful).POST /api/public/widget/trackRecords an anonymous widget usage event (e.g. “widget opened”) for the analyses in the dashboard.POST /api/public/widget/voice-transcribeConverts a visitor's voice recording into text (voice input), if the voice feature is enabled for the widget.POST /api/public/widget/voice-speakConverts text into speech (voice output in the widget), if the voice feature is enabled.