POST/api/public/widget/message

Skickar en besökares meddelande till chattboten och returnerar dess svar – chattwidgetens centrala slutpunkt.

Skicka `widget_code`, `message`, `visitor_id` och – från andra meddelandet – `session_id` från det föregående svaret. Vid det första anropet i ett nytt samtal lämnar du `session_id` tom eller sätter den till `null`. Svaret innehåller i objektet `data` `session_id`, svarstexten `response` samt eventuellt knappar (`buttons`), produktförslag (`products`) och samtalsstatus (`state`). Headern `X-Widget-Token` med inbäddningstoken och `widget_code` krävs. Saknas token svarar servern med 401 `WIDGET_TOKEN_MISSING`, är den ogiltig med 401 `WIDGET_TOKEN_INVALID`; anrop från domäner som inte godkänts får 403 `WIDGET_ORIGIN_DENIED`, en inaktiverad widget 404 `WIDGET_DISABLED`. Saknas `visitor_id` svarar servern med 400 `VISITOR_ID_REQUIRED`. Anropet är inte idempotent: varje sändning skapar ytterligare ett besökarmeddelande och ytterligare ett svar. Lås inmatningen medan en förfrågan pågår och upprepa den inte automatiskt.

Översikt

Anrop: POST /api/public/widget/message. Endpointen tillhör gruppen ”Chattwidget” i Zentor Apps API. Den kräver en giltig widget-inbäddningstoken. Anropet är inte idempotent: Varje lyckat anrop utlöser åtgärden på nytt. Obligatoriska parametrar: widget_code (body), message (body), visitor_id (body). Valfria parametrar: session_id (body). Dokumenterade felfall: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Exempelsvaret nedan visar strukturen för ett lyckat svar i JSON-format.

Autentisering & säkerhet

Widget-embed-token (header X-Widget-Token) + lista över godkända origins

Idempotent: Nej

Parametrar

widget_code(body, string, obligatorisk)— Widget-kod från din inbäddningskod
message(body, string, obligatorisk)— Texten i besökarens meddelande
visitor_id(body, string, obligatorisk)— Besökar-ID som widgeten genererar och lagrar i webbläsaren
session_id(body, string)— Sessions-ID från det föregående svaret; tomt eller `null` vid det första anropet i ett nytt samtal

Exempel på request

{"widget_code":"...","message":"Hej, vad kan Zentor App göra?","visitor_id":"<UUID eller klientgenererat ID>"}

Exempel på response

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

Felkoder

401 WIDGET_TOKEN_MISSING — Headern `X-Widget-Token` saknas.
401 WIDGET_TOKEN_INVALID — Inbäddningstoken matchar inte widget-koden.
400 VISITOR_ID_REQUIRED — Fältet `visitor_id` saknas.

Verifierat beteende

Ett giltigt meddelande returnerar 200 med chattbotens svar; en saknad eller ogiltig token samt en saknad `visitor_id` returnerar de dokumenterade felkoderna.

Chattwidget

GET /api/public/widget/healthEnkel tillgänglighetskontroll av widget-tjänsten.GET /api/public/widget/config/:widget_codeReturnerar en widgets offentliga konfiguration (visningsnamn, välkomsttext, design, språk, röstfunktion) för initiering i webbläsaren.GET /api/public/widget/historyLaddar den tidigare meddelandehistoriken för ett widget-samtal, till exempel efter att sidan har laddats om.POST /api/public/widget/pollHämtar meddelanden som mottagits efter en viss tidpunkt – till exempel svaret från en medarbetare som har tagit över samtalet.POST /api/public/widget/ratingSparar besökarens omdöme om ett samtal (hjälpsamt eller inte hjälpsamt).POST /api/public/widget/trackRegistrerar en anonym widget-användningshändelse (t.ex. ”widget öppnad”) för analyserna i kontrollpanelen).POST /api/public/widget/voice-transcribeKonverterar en besökares röstinspelning till text (röstinmatning), om röstfunktionen är aktiverad för widgeten.POST /api/public/widget/voice-speakKonverterar text till tal (röstutmatning i widgeten), om röstfunktionen är aktiverad.

Relaterade artiklar

← Chattwidget