POST/api/public/widget/message
Ithumela umlayezo wesivakatshi ku-chatbot njalo inikeze impendulo yayo – isiphetho esimaphakathi sewijethi yengxoxo.
Dlulisani `widget_code`, `message`, `visitor_id` njalo – kusukela kumlayezo wesibili – `session_id` evela empendulweni yakuqala. Nxa libiza kokuqala ingxoxo entsha, tshiyani `session_id` ingelalutho kumbe liyihlele ngo-`null`. Impendulo ilomunqulo `data` i-`session_id`, umbhalo wempendulo `response`, kanye lokunye nxa kudingeka amabhatani (`buttons`), izikhuthazo zemikhiqizo (`products`) lesimo sengxoxo (`state`). I-header `X-Widget-Token` elethokheni yokufaka le-`widget_code` kuyadingakala. Nxa ithokheni kayikho, iseva iphendula ngo-401 `WIDGET_TOKEN_MISSING`, nxa kayivumelekile ngo-401 `WIDGET_TOKEN_INVALID`; izicelo ezivela ezizindeni ezingavuliweyo zithola 403 `WIDGET_ORIGIN_DENIED`, iwijethi evalwe 404 `WIDGET_DISABLED`. Nxa `visitor_id` kayikho, iseva iphendula ngo-400 `VISITOR_ID_REQUIRED`. Isicelo kasilingananisi: ukuthumela ngakunye kwakha umlayezo omutsha wesivakatshi lempendulo enye njalo. Valani ukufaka nxa isicelo siqhubeka, njalo lingasiphindi ngokuzenzakalela.
Isifinyezo
Ukubiza: POST /api/public/widget/message. Le endpoint ingeyeqembu elithi “Iwijethi yengxoxo” le-API ye-Zentor App. Idinga i-widget embed token esebenzayo. Ukubiza kakusiyo i-idempotent: ukubiza ngakunye okuphumelelayo kuqalisa isenzo kutsha. Amapharamitha adingekayo: widget_code (body), message (body), visitor_id (body). Amapharamitha okukhetha: session_id (body). Izimo zamaphutha ezibhaliweyo: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Isibonelo sempendulo ngezansi sitshengisa ukwakheka kwempendulo ephumelelayo ngefomethi ye-JSON.
Ukuqinisekisa ubuwena lokuvikeleka
I-Embed-Token ye-widget (i-header X-Widget-Token) + uhlu lwama-Origin avunyelweyo
I-idempotent: Hatshi
Amapharamitha
widget_code(body, string, kuyadingeka)— Ikhodi yewijethi evela ekhodini yakho yokufakamessage(body, string, kuyadingeka)— Umbhalo wemlayezo wesivakatshivisitor_id(body, string, kuyadingeka)— I-ID yesivakatshi edalwa yiwijethi njalo igciniwe ebhrawuzenisession_id(body, string)— I-ID yeseshini evela empendulweni yakuqala; ekubizweni kokuqala kwengxoxo entsha ingelalutho kumbe `null`Isibonelo sesicelo (request)
{"widget_code":"...","message":"Sawubona, iZentor App ingenzani?","visitor_id":"<UUID kumbe i-ID eyenziwe ngumthengi>"}Isibonelo sempendulo (response)
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Amakhodi amaphutha
401 WIDGET_TOKEN_MISSING — Iheda `X-Widget-Token` kayikho.401 WIDGET_TOKEN_INVALID — Ithokheni yokufaka kayihambisani nekhodi yewijethi.400 VISITOR_ID_REQUIRED — Insimu `visitor_id` kayikho.Ukuziphatha okuhlolwe
Umlayezo osemthethweni unikeza 200 lempendulo ye-chatbot; ithokheni kayikho kumbe kayivumelekile kanye ne-`visitor_id` kayikho zinikeza amakhodi wamaphutha abhaliweyo.
Iwijethi yengxoxo
GET /api/public/widget/healthUkuhlolwa okulula kokutholakala kwesevisi yewijethi.GET /api/public/widget/config/:widget_codeInikeza ukuhlelwa komphakathi kwewijethi (ibizo elibonakalayo, umbhalo wokwamukela, idizayini, ulimi, umsebenzi wezwi) wokuqaliswa kubhrawuza.GET /api/public/widget/historyIlayitsha umlando wemilayezo esekhona wengxoxo yewijethi, isibonelo ngemva kokuphindwa kulayishwe ikhasi.POST /api/public/widget/pollIthatha imilayezo etholwe ngemva kwesikhathi esithile – isibonelo impendulo yesisebenzi esithatha ingxoxo.POST /api/public/widget/ratingIgcina isilinganiso sesivakatshi ngengxoxo (kuyasiza kumbe kakusizi).POST /api/public/widget/trackIbhala izenzakalo yokusetshenziswa engaziwa yewijethi (isib. „iwijethi ivuliwe“) yokuhlaziywa kwedashboard.POST /api/public/widget/voice-transcribeIguqula ukuqoshwa kwezwi kwesivakatshi kube umbhalo (ukufakwa kwezwi), nxa umsebenzi wezwi wewijethi uvuliwe.POST /api/public/widget/voice-speakIguqula umbhalo kube ulimi olukhulunywayo (ukukhishwa kwezwi ewijethini), nxa umsebenzi wezwi uvuliwe.