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 kupachika
message(body, string, inahitajika)— Maandishi ya ujumbe wa mgeni
visitor_id(body, string, inahitajika)— Kitambulisho cha mgeni kinachotengenezwa na wijeti na kuhifadhiwa kwenye kivinjari
session_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.

Makala zinazohusiana

← Wijeti ya mazungumzo