POST/api/public/widget/message
Hutuma ujumbe wa mgeni kwa chatbot na kutoa jibu lake – kipengele kikuu cha wijeti ya gumzo.
Pitisheni `widget_code`, `message`, `visitor_id` na – kuanzia ujumbe wa pili – `session_id` kutoka jibu lililotangulia. Mnapopiga kwa mara ya kwanza mazungumzo mapya, acheni `session_id` tupu au wekeni `null`. Jibu linajumuisha ndani ya kipengele `data` `session_id`, maandishi ya jibu `response`, pamoja na, inapofaa, vitufe (`buttons`), mapendekezo ya bidhaa (`products`) na hali ya mazungumzo (`state`). Kichwa `X-Widget-Token` chenye tokeni ya kupachika na `widget_code` ni lazima. Tokeni ikikosekana, seva hujibu kwa 401 `WIDGET_TOKEN_MISSING`, ikiwa batili kwa 401 `WIDGET_TOKEN_INVALID`; maombi kutoka vikoa visivyoidhinishwa hupokea 403 `WIDGET_ORIGIN_DENIED`, wijeti iliyozimwa 404 `WIDGET_DISABLED`. `visitor_id` ikikosekana, seva hujibu kwa 400 `VISITOR_ID_REQUIRED`. Ombi hili si idempotent: kila kutuma huzalisha ujumbe mwingine wa mgeni na jibu lingine. Funga uwekaji wakati ombi linaendelea, na lisirudie kiotomatiki.
Muhtasari
Mwito: POST /api/public/widget/message. Endpoint hii ni sehemu ya kundi la “Wijeti ya mazungumzo” la API ya Zentor App. Inahitaji tokeni halali ya kupachika wijeti (widget embed token). Mwito huu si idempotent: kila mwito uliofanikiwa huanzisha kitendo upya. Vigezo vya lazima: widget_code (body), message (body), visitor_id (body). Vigezo vya hiari: session_id (body). Hali za hitilafu zilizoandikwa: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Jibu la mfano hapa chini linaonyesha muundo wa jibu lililofanikiwa katika umbizo la JSON.
Uthibitishaji na ulinzi
Embed token ya widget (header X-Widget-Token) + orodha ya origins zilizoidhinishwa
Idempotent: Hapana
Vigezo
widget_code(body, string, inahitajika)— Msimbo wa wijeti kutoka msimbo wako wa kupachikamessage(body, string, inahitajika)— Maandishi ya ujumbe wa mgenivisitor_id(body, string, inahitajika)— Kitambulisho cha mgeni kinachotengenezwa na wijeti na kuhifadhiwa kwenye kivinjarisession_id(body, string)— Kitambulisho cha kipindi kutoka jibu lililotangulia; kwenye wito wa kwanza wa mazungumzo mapya tupu au `null`Mfano wa ombi (request)
{"widget_code":"...","message":"Habari, Zentor App inaweza kufanya nini?","visitor_id":"<UUID au ID iliyozalishwa upande wa mteja>"}Mfano wa jibu (response)
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Misimbo ya hitilafu
401 WIDGET_TOKEN_MISSING — Kichwa `X-Widget-Token` kinakosekana.401 WIDGET_TOKEN_INVALID — Tokeni ya kupachika haifanani na msimbo wa wijeti.400 VISITOR_ID_REQUIRED — Sehemu `visitor_id` inakosekana.Tabia iliyoangaliwa
Ujumbe sahihi hutoa 200 na jibu la chatbot; tokeni inayokosekana au batili pamoja na `visitor_id` inayokosekana hutoa misimbo ya hitilafu iliyoandikwa.
Wijeti ya mazungumzo
GET /api/public/widget/healthUkaguzi rahisi wa upatikanaji wa huduma ya wijeti.GET /api/public/widget/config/:widget_codeHutoa usanidi wa umma wa wijeti (jina linaloonyeshwa, ujumbe wa karibu, mandhari, lugha, kipengele cha sauti) kwa uanzishaji kwenye kivinjari.GET /api/public/widget/historyHupakia historia iliyopo ya ujumbe wa mazungumzo ya wijeti, kwa mfano baada ya kupakia upya ukurasa.POST /api/public/widget/pollInarudisha ujumbe uliopokelewa baada ya wakati fulani – kwa mfano jibu la mfanyakazi aliyechukua mazungumzo.POST /api/public/widget/ratingHuhifadhi tathmini ya mgeni kuhusu mazungumzo (yenye manufaa au bila manufaa).POST /api/public/widget/trackHurekodi tukio la matumizi lisilojulikana la wijeti (mf. „wijeti imefunguliwa“) kwa uchambuzi kwenye dashibodi.POST /api/public/widget/voice-transcribeHubadilisha rekodi ya sauti ya mgeni kuwa maandishi (uwekaji wa sauti), iwapo kipengele cha sauti cha wijeti kimewezeshwa.POST /api/public/widget/voice-speakHubadilisha maandishi kuwa lugha inayosemwa (matokeo ya sauti kwenye wijeti), iwapo kipengele cha sauti kimewezeshwa.