POST/api/public/widget/voice-transcribe

Converts a visitor's voice recording into text (voice input), if the voice feature is enabled for the widget.

Send `widget_code` and the audio data in the `audio` field as `multipart/form-data`. The response contains the recognised text, which you then send via `POST /api/public/widget/message`. Whether the voice feature is active is indicated by `voice_enabled` in the widget configuration. 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`. Zentor sets up the voice feature for your widget.

Overview

Call: POST /api/public/widget/voice-transcribe. 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), audio (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: No

Parameters

widget_code(body, string, required)— Widget code from your embed code
audio(body, binary, required)— Audio recording as a file (`multipart/form-data`)

Example 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-speakConverts text into speech (voice output in the widget), if the voice feature is enabled.

Related articles

← Chat Widget