POST/api/public/widget/message

Sends a visitor chat message to the chatbot and returns its reply — the central endpoint of the chat widget.

`POST /api/public/widget/message` is the central endpoint used by the embedded chat widget to send a visitor message to the chatbot and receive the resulting reply. The request requires the widget embed token in the `X-Widget-Token` header and is checked against the configured origin allowlist. The body includes the `widget_code`, the visitor’s `message`, a `visitor_id` and the session information required by the active conversation flow. The operation is not idempotent. Sending the same request twice can create two user messages and two bot responses. The widget should therefore prevent double submission while a request is pending and should not retry automatically unless it can prove that the previous request never reached the server. A unique client-side message state can help the interface avoid displaying the same outgoing text twice, but it does not change the backend semantics. Before calling the message endpoint, the widget should load its public configuration and establish the correct session context. The token is shown in clear text only once when the widget is provisioned and must not be exposed in public logs, support screenshots or analytics payloads. If the page origin is not approved, the server can reject the request with `WIDGET_ORIGIN_DENIED`. Copying the integration to another domain is therefore not sufficient to make it work. Typical client errors include a missing message, an invalid widget code, absent visitor or session values, a missing token and an origin mismatch. The UI should distinguish these configuration problems from a temporary backend failure. An empty or whitespace-only message should be blocked before submission. If the response is asynchronous because a human has taken over, the widget uses the dedicated poll route to receive later messages. A realistic flow is: load widget configuration, open or restore a session, submit the visitor’s text through this endpoint, render the returned bot message and continue polling when the conversation enters handover. The endpoint does not create a developer API session and should not be called from arbitrary server integrations as a substitute for a documented backend API.

{"widget_code":"...","message":"Hello, what can Zentor App do?","visitor_id":"<UUID or client-generated ID>"}

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}