POST/api/public/widget/message
Stuur 'n boodskap van die besoeker aan die kletsbot en lewer sy antwoord – die sentrale endpunt van die kletswidget.
Gee `widget_code`, `message`, die `visitor_id` en – van die tweede boodskap af – die `session_id` uit die vorige antwoord deur. By die eerste oproep van 'n nuwe konversasie laat u `session_id` leeg of stel dit op `null`. Die antwoord bevat in die `data`-objek die `session_id`, die antwoordteks `response`, asook waar toepaslik knoppies (`buttons`), produkvoorstelle (`products`) en die gespreksstatus (`state`). Die header `X-Widget-Token` met die inbedtoken en `widget_code` is verpligtend. Ontbreek die token, antwoord die bediener met 401 `WIDGET_TOKEN_MISSING`, is dit ongeldig met 401 `WIDGET_TOKEN_INVALID`; oproepe van nie-vrygestelde domeine ontvang 403 `WIDGET_ORIGIN_DENIED`, 'n gedeaktiveerde widget 404 `WIDGET_DISABLED`. Ontbreek `visitor_id`, antwoord die bediener met 400 `VISITOR_ID_REQUIRED`. Die oproep is nie idempotent nie: elke sending skep 'n verdere besoekerboodskap en 'n verdere antwoord. Sluit die invoer terwyl 'n versoek loop, en herhaal dit nie outomaties nie.
Oorsig
Oproep: POST /api/public/widget/message. Hierdie eindpunt behoort tot die groep “Chat-widget” van die Zentor App-API. Dit vereis ’n geldige widget-inbedtoken. Die oproep is nie idempotent nie: elke suksesvolle oproep aktiveer die aksie opnuut. Verpligte parameters: widget_code (body), message (body), visitor_id (body). Opsionele parameters: session_id (body). Gedokumenteerde foutgevalle: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Die voorbeeldrespons hieronder toon die struktuur van ’n suksesvolle respons in JSON-formaat.
Verifikasie en sekuriteit
Widget-inbedtoken (X-Widget-Token-header) + lys van toegelate origins
Idempotent: Nee
Parameters
widget_code(body, string, vereis)— Widget-kode uit u inbedkodemessage(body, string, vereis)— Teks van die besoekerboodskapvisitor_id(body, string, vereis)— Besoeker-ID wat die widget genereer en in die blaaier stoorsession_id(body, string)— Sessie-ID uit die vorige antwoord; by die eerste oproep van 'n nuwe konversasie leeg of `null`Voorbeeldversoek
{"widget_code":"...","message":"Hallo, wat kan Zentor App doen?","visitor_id":"<UUID of kliëntgegenereerde ID>"}Voorbeeldrespons
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Foutkodes
401 WIDGET_TOKEN_MISSING — Die header `X-Widget-Token` ontbreek.401 WIDGET_TOKEN_INVALID — Die inbedtoken pas nie by die widget-kode nie.400 VISITOR_ID_REQUIRED — Die veld `visitor_id` ontbreek.Gekontroleerde gedrag
'n Geldige boodskap lewer 200 met die kletsbot se antwoord; 'n ontbrekende of ongeldige token asook 'n ontbrekende `visitor_id` lewer die gedokumenteerde foutkodes.
Chat-widget
GET /api/public/widget/healthEenvoudige bereikbaarheidstoets van die widget-diens.GET /api/public/widget/config/:widget_codeLewer die openbare konfigurasie van 'n widget (vertoonnaam, verwelkomingsteks, ontwerp, taal, spraakfunksie) vir die inisialisering in die blaaier.GET /api/public/widget/historyLaai die bestaande boodskapgeskiedenis van 'n widget-konversasie, byvoorbeeld na die herlaai van die bladsy.POST /api/public/widget/pollHaal boodskappe op wat ná 'n tydstip ontvang is – byvoorbeeld die antwoord van 'n personeellid wat die gesprek oorgeneem het.POST /api/public/widget/ratingStoor die beoordeling van die besoeker oor 'n konversasie (nuttig of nie nuttig nie).POST /api/public/widget/trackRegistreer 'n anonieme gebruiksgebeurtenis van die widget (bv. „widget geopen“) vir die evaluasies in die kontrolepaneel.POST /api/public/widget/voice-transcribeVerander 'n stemopname van die besoeker in teks (spraakinvoer), indien die spraakfunksie vir die widget geaktiveer is.POST /api/public/widget/voice-speakVerander teks in gesproke taal (spraakuitvoer in die widget), indien die spraakfunksie geaktiveer is.