POST/api/public/widget/message

Odošle správu návštevníka chatbotovi a vráti jeho odpoveď – centrálny endpoint chatovacieho widgetu.

Odošlite `widget_code`, `message`, `visitor_id` a – od druhej správy – `session_id` z predchádzajúcej odpovede. Pri prvom volaní novej konverzácie nechajte `session_id` prázdne alebo ho nastavte na `null`. Odpoveď obsahuje v objekte `data` `session_id`, text odpovede `response` a prípadne tlačidlá (`buttons`), návrhy produktov (`products`) a stav konverzácie (`state`). Hlavička `X-Widget-Token` s vkladacím tokenom a `widget_code` sú povinné. Ak token chýba, server odpovie 401 `WIDGET_TOKEN_MISSING`, ak je neplatný, 401 `WIDGET_TOKEN_INVALID`; volania z nepovolených domén dostanú 403 `WIDGET_ORIGIN_DENIED`, deaktivovaný widget 404 `WIDGET_DISABLED`. Chýba-li `visitor_id`, server odpovie 400 `VISITOR_ID_REQUIRED`. Volanie nie je idempotentné: každé odoslanie vytvorí ďalšiu správu návštevníka a ďalšiu odpoveď. Zablokujte vstup, kým požiadavka trvá, a automaticky ho neopakujte.

Prehľad

Volanie: POST /api/public/widget/message. Tento endpoint patrí do skupiny „Chatový widget“ API aplikácie Zentor App. Vyžaduje platný token na vloženie widgetu. Volanie nie je idempotentné: Každé úspešné volanie akciu spustí znova. Povinné parametre: widget_code (body), message (body), visitor_id (body). Voliteľné parametre: session_id (body). Zdokumentované chybové prípady: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Ukážková odpoveď nižšie zobrazuje štruktúru úspešnej odpovede vo formáte JSON.

Autentifikácia a zabezpečenie

Embed token widgetu (hlavička X-Widget-Token) + zoznam povolených pôvodov (Origin)

Idempotentné: Nie

Parametre

widget_code(body, string, povinné)— Kód widgetu z vášho vkladacieho kódu
message(body, string, povinné)— Text správy návštevníka
visitor_id(body, string, povinné)— ID návštevníka vygenerované widgetom a uložené v prehliadači
session_id(body, string)— ID relácie z predchádzajúcej odpovede; prázdne alebo `null` pri prvom volaní novej konverzácie

Príklad požiadavky

{"widget_code":"...","message":"Ahoj, čo dokáže Zentor App?","visitor_id":"<UUID alebo ID vygenerované klientom>"}

Príklad odpovede

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

Chybové kódy

401 WIDGET_TOKEN_MISSING — Chýba hlavička `X-Widget-Token`.
401 WIDGET_TOKEN_INVALID — Vkladací token nezodpovedá kódu widgetu.
400 VISITOR_ID_REQUIRED — Chýba pole `visitor_id`.

Overené správanie

Platná správa vráti 200 s odpoveďou chatbota; chýbajúci alebo neplatný token a chýbajúce `visitor_id` vrátia zdokumentované chybové kódy.

Chatový widget

GET /api/public/widget/healthJednoduchá kontrola dostupnosti služby widgetu.GET /api/public/widget/config/:widget_codeVracia verejnú konfiguráciu widgetu (zobrazovaný názov, uvítací text, dizajn, jazyk, hlasová funkcia) na inicializáciu v prehliadači.GET /api/public/widget/historyNačíta predchádzajúcu históriu správ konverzácie widgetu, napríklad po opätovnom načítaní stránky.POST /api/public/widget/pollZíska správy prijaté po určitom okamihu – napríklad odpoveď pracovníka, ktorý prevzal konverzáciu.POST /api/public/widget/ratingUloží hodnotenie návštevníka konverzácie (užitočné alebo neužitočné).POST /api/public/widget/trackZaznamená anonymnú udalosť využitia widgetu (napr. „widget otvorený“) pre analýzy v dashboarde.POST /api/public/widget/voice-transcribePrevedie hlasovú nahrávku návštevníka na text (hlasový vstup), ak je pre widget aktivovaná hlasová funkcia.POST /api/public/widget/voice-speakPrevedie text na hovorené slovo (hlasový výstup v widgete), ak je hlasová funkcia aktivovaná.

Súvisiace články

← Chatový widget