POST/api/public/widget/message
Pošlje sporočilo obiskovalca klepetalnemu robotu in vrne njegov odgovor – osrednja končna točka klepetalnega gradnika.
Pošljite `widget_code`, `message`, `visitor_id` in – od drugega sporočila naprej – `session_id` iz prejšnjega odgovora. Pri prvem klicu novega pogovora pustite `session_id` prazno ali ga nastavite na `null`. Odgovor v objektu `data` vsebuje `session_id`, besedilo odgovora `response` ter po potrebi gumbe (`buttons`), predloge izdelkov (`products`) in stanje pogovora (`state`). Glava `X-Widget-Token` z žetonom za vdelavo in `widget_code` sta obvezna. Če žeton manjka, strežnik odgovori s 401 `WIDGET_TOKEN_MISSING`, če je neveljaven, s 401 `WIDGET_TOKEN_INVALID`; klici z neodobrenih domen prejmejo 403 `WIDGET_ORIGIN_DENIED`, deaktiviran gradnik 404 `WIDGET_DISABLED`. Če manjka `visitor_id`, strežnik odgovori s 400 `VISITOR_ID_REQUIRED`. Klic ni idempotenten: vsako pošiljanje ustvari nadaljnje sporočilo obiskovalca in nadaljnji odgovor. Blokirajte vnos, dokler zahteva teče, in je ne ponavljajte samodejno.
Pregled
Klic: POST /api/public/widget/message. Ta endpoint spada v skupino »Klepetalni gradnik« API-ja Zentor App. Zahteva veljaven žeton za vdelavo pripomočka (widget embed token). Klic ni idempotenten: vsak uspešen klic znova sproži dejanje. Obvezni parametri: widget_code (body), message (body), visitor_id (body). Neobvezni parametri: session_id (body). Dokumentirani primeri napak: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Spodnji primer odgovora prikazuje strukturo uspešnega odgovora v formatu JSON.
Avtentikacija in zaščita
Žeton za vdelavo gradnika (glava X-Widget-Token) + seznam dovoljenih izvorov
Idempotentno: Ne
Parametri
widget_code(body, string, obvezno)— Koda gradnika iz vaše kode za vdelavomessage(body, string, obvezno)— Besedilo sporočila obiskovalcavisitor_id(body, string, obvezno)— ID obiskovalca, ki ga gradnik ustvari in shrani v brskalnikusession_id(body, string)— ID seje iz prejšnjega odgovora; pri prvem klicu novega pogovora prazno ali `null`Primer zahteve
{"widget_code":"...","message":"Pozdravljeni, kaj zmore Zentor App?","visitor_id":"<UUID ali ID, ustvarjen na odjemalcu>"}Primer odgovora
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Kode napak
401 WIDGET_TOKEN_MISSING — Manjka glava `X-Widget-Token`.401 WIDGET_TOKEN_INVALID — Žeton za vdelavo se ne ujema s kodo gradnika.400 VISITOR_ID_REQUIRED — Manjka polje `visitor_id`.Preverjeno vedenje
Veljavno sporočilo vrne 200 z odgovorom klepetalnega robota; manjkajoč ali neveljaven žeton ter manjkajoč `visitor_id` vrnejo dokumentirane kode napak.
Klepetalni gradnik
GET /api/public/widget/healthEnostavno preverjanje dosegljivosti storitve gradnika (widgeta).GET /api/public/widget/config/:widget_codeVrne javno konfiguracijo gradnika (prikazno ime, pozdravno besedilo, oblikovanje, jezik, glasovno funkcijo) za inicializacijo v brskalniku.GET /api/public/widget/historyNaloži pretekli potek sporočil pogovora gradnika, na primer po ponovnem nalaganju strani.POST /api/public/widget/pollPrikliče sporočila, prejeta po določenem trenutku – na primer odgovor sodelavca, ki je prevzel pogovor.POST /api/public/widget/ratingShrani oceno obiskovalca za pogovor (koristno ali ni koristno).POST /api/public/widget/trackZajame anonimen dogodek uporabe gradnika (npr. „gradnik odprt“) za analize na nadzorni plošči.POST /api/public/widget/voice-transcribePretvori glasovni posnetek obiskovalca v besedilo (glasovni vnos), če je glasovna funkcija za gradnik aktivirana.POST /api/public/widget/voice-speakPretvori besedilo v govorjeno govorico (glasovni izhod v gradniku), če je glasovna funkcija aktivirana.