POST/api/public/widget/message
Ithumela umyalezo wendwendwe ku-chatbot kwaye inikeze impendulo yayo – isiphelo esisembindini sewijethi yencoko.
Nikezela `widget_code`, `message`, `visitor_id` kwaye – ukusuka kumyalezo wesibini – `session_id` esivela kwimpendulo yangaphambili. Xa ubiza okokuqala incoko entsha, shiya `session_id` ingenanto okanye uyise ku-`null`. Impendulo iqulethe kwisikhongozelo `data` i-`session_id`, umbhalo wempendulo `response`, kunye nokunye xa kufuneka amaqhosha (`buttons`), iingcebiso zeemveliso (`products`) kunye nesimo sencoko (`state`). I-header `X-Widget-Token` enetoken yokufaka ne-`widget_code` iyafuneka. Ukuba itoken ayikho, iseva iphendula ngo-401 `WIDGET_TOKEN_MISSING`, ukuba ayivumelekile ngo-401 `WIDGET_TOKEN_INVALID`; izicelo ezivela kwiidomeyini ezingavuliweyo zifumana 403 `WIDGET_ORIGIN_DENIED`, iwijethi ecinezelweyo 404 `WIDGET_DISABLED`. Ukuba `visitor_id` ayikho, iseva iphendula ngo-400 `VISITOR_ID_REQUIRED`. Isicelo asilingananisi: ukuthumela ngakunye kudala umyalezo omtsha wendwendwe kunye nempendulo yesibini. Vala ukufaka ngelixa isicelo siqhubeka, kwaye musa kusiphinda ngokuzenzekelayo.
Ushwankathelo
Ukubiza: POST /api/public/widget/message. Le endpoint yeyeqela elithi “Iwijethi yencoko” le-API ye-Zentor App. Ifuna i-widget embed token esebenzayo. Ukubiza ayisiyo i-idempotent: ukubiza ngakunye okuphumelelayo kuqalisa isenzo kwakhona. Iipharamitha ezinyanzelekileyo: widget_code (body), message (body), visitor_id (body). Iipharamitha ozikhethayo: session_id (body). Iimeko zeempazamo ezibhaliweyo: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Impendulo engumzekelo engezantsi ibonisa ulwakhiwo lwempendulo ephumelelayo ngefomathi ye-JSON.
Ukuqinisekiswa nokhuseleko
Widget embed token (header X-Widget-Token) + uluhlu lwee-origin ezivunyiweyo
Idempotent: Hayi
Iiparamitha
widget_code(body, string, kuyafuneka)— Ikhowudi yewijethi evela kwikhowudi yakho yokufakamessage(body, string, kuyafuneka)— Umbhalo womyalezo wendwendwevisitor_id(body, string, kuyafuneka)— I-ID yendwendwe eyenziwa yiwijethi kwaye igcinwe kwibhrawuzasession_id(body, string)— I-ID yeseshoni evela kwimpendulo yangaphambili; ekubizweni kokuqala kwincoko entsha ingenanto okanye `null`Umzekelo we-request
{"widget_code":"...","message":"Molo, i-Zentor App ingenza ntoni?","visitor_id":"<UUID okanye i-ID eyenziwe ngumthengi>"}Umzekelo we-response
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Iikhowudi zeempazamo
401 WIDGET_TOKEN_MISSING — Iheda `X-Widget-Token` ayikho.401 WIDGET_TOKEN_INVALID — Itoken yokufaka ayihambelani nekhowudi yewijethi.400 VISITOR_ID_REQUIRED — Intsimi `visitor_id` ayikho.Ukuziphatha okujongwe
Umyalezo osemthethweni unikeza 200 nempendulo ye-chatbot; itoken engekho okanye engavumelekileyo kunye ne-`visitor_id` engekho zinikeza iikhowudi zeempazamo ezibhaliweyo.
Iwijethi yencoko
GET /api/public/widget/healthUvavanyo olulula lokufikeleleka kwenkonzo yewijethi.GET /api/public/widget/config/:widget_codeInikezela ukucwangciso lokawonke-wonke lwewijethi (igama elibonakalayo, umbhalo wokwamkela, uyilo, ulwimi, umsebenzi wezwi) wokuqaliswa kwibhrawuza.GET /api/public/widget/historyIlayisha imbali yemiyalezo ekhoyo yencoko yewijethi, umzekelo emva kokulayishwa kwakhona kwephepha.POST /api/public/widget/pollIkhupha imiyalezo efunyenwe emva kwexesha elithile – umzekelo impendulo yomsebenzi othathileyo incoko.POST /api/public/widget/ratingIgcina isivakalisi sendwendwe malunga nencoko (kuluncedo okanye akuluncedo).POST /api/public/widget/trackIrekhoda isiganeko esingaziwayo sokusetyenziswa kwewijethi (umz. „iwijethi ivuliwe“) sokuhlalutywa kwedashboard.POST /api/public/widget/voice-transcribeIguqula ukushicilelwa kwezwi kwendwendwe kube umbhalo (ukufakwa kwezwi), ukuba umsebenzi wezwi wewijethi uvuliwe.POST /api/public/widget/voice-speakIguqula umbhalo kube ulwimi olukhulunywayo (ukukhutshwa kwezwi kwiwijethi), ukuba umsebenzi wezwi uvuliwe.