POST/api/public/widget/voice-speak
Converts text into speech (voice output in the widget), if the voice feature is enabled.
Send `widget_code` and the text to be read aloud in `text`. The response contains the audio data for playback in the browser. For direct playback via an `<audio>` element, the same path is also available via GET. If `widget_code` is missing, the server responds with 400 `WIDGET_CODE_REQUIRED`; if the voice feature is not enabled or currently unavailable, with 503 `VOICE_UNAVAILABLE`. Only start a new playback once the previous one has finished.
Overview
Call: POST /api/public/widget/voice-speak. This endpoint belongs to the “Chat Widget” group of the Zentor App API. It requires a valid widget embed token. The call is idempotent: repeating it with the same input returns the same result. Required parameters: widget_code (body), text (body). Documented error cases: 400 WIDGET_CODE_REQUIRED, 503 VOICE_UNAVAILABLE. The example response below shows the structure of a successful JSON response.
Auth & Security
Widget embed token (X-Widget-Token header) + origin allowlist
Idempotent: Yes
Parameters
widget_code(body, string, required)— Widget code from your embed codetext(body, string, required)— Text to be read aloudExample Response
{"ok":false,"error":{"code":"VOICE_UNAVAILABLE","message":"Sprachfunktion aktuell nicht verfügbar."}}Error Codes
400 WIDGET_CODE_REQUIRED — The `widget_code` field is missing.503 VOICE_UNAVAILABLE — The voice feature is not enabled for this widget or is currently unavailable.Verified behaviour
A missing `widget_code` returns 400 `WIDGET_CODE_REQUIRED`, a widget without the voice feature 503 `VOICE_UNAVAILABLE`. The success case requires a widget with the voice feature enabled.
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.POST /api/public/widget/messageSends a visitor's message to the chatbot and returns its reply – the central endpoint of the chat widget.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.