POST/api/public/widget/message

Dërgon një mesazh të vizitorit te chatbot-i dhe kthen përgjigjen e tij – endpoint-i qendror i widget-it të bisedës.

Dërgoni `widget_code`, `message`, `visitor_id` dhe – nga mesazhi i dytë e tutje – `session_id` nga përgjigja e mëparshme. Në thirrjen e parë të një bisede të re, lëreni `session_id` bosh ose vendoseni në `null`. Përgjigja përmban në objektin `data` `session_id`, tekstin e përgjigjes `response`, si dhe, sipas rastit, butonat (`buttons`), propozimet e produkteve (`products`) dhe gjendjen e bisedës (`state`). Header-i `X-Widget-Token` me token-in e ngulitjes dhe `widget_code` janë të detyrueshme. Nëse token-i mungon, serveri përgjigjet me 401 `WIDGET_TOKEN_MISSING`, nëse është i pavlefshëm me 401 `WIDGET_TOKEN_INVALID`; thirrjet nga domene të pamiratuara marrin 403 `WIDGET_ORIGIN_DENIED`, një widget i deaktivizuar 404 `WIDGET_DISABLED`. Nëse mungon `visitor_id`, serveri përgjigjet me 400 `VISITOR_ID_REQUIRED`. Thirrja nuk është idempotente: çdo dërgim krijon një mesazh tjetër të vizitorit dhe një përgjigje tjetër. Blokoni hyrjen derisa një kërkesë është në proces dhe mos e përsërisni automatikisht.

Përmbledhje

Thirrja: POST /api/public/widget/message. Ky endpoint i përket grupit “Widget-i i bisedës” të API-së së Zentor App. Kërkon një token të vlefshëm për ngulitjen e widget-it (widget embed token). Thirrja nuk është idempotente: çdo thirrje e suksesshme e shkakton veprimin përsëri. Parametrat e detyrueshëm: widget_code (body), message (body), visitor_id (body). Parametrat opsionalë: session_id (body). Rastet e dokumentuara të gabimeve: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Përgjigjja shembull më poshtë tregon strukturën e një përgjigjeje të suksesshme në formatin JSON.

Autentifikimi dhe siguria

Widget-Embed-Token (header X-Widget-Token) + lista e lejimeve të Origin

Idempotent: Jo

Parametrat

widget_code(body, string, i detyrueshëm)— Kodi i widget-it nga kodi juaj i integrimit
message(body, string, i detyrueshëm)— Teksti i mesazhit të vizitorit
visitor_id(body, string, i detyrueshëm)— ID-ja e vizitorit, që e krijon dhe e ruan widget-i në shfletues
session_id(body, string)— ID-ja e seancës nga përgjigja e mëparshme; e bosh ose `null` në thirrjen e parë të një bisede të re

Shembull request-i

{"widget_code":"...","message":"Përshëndetje, çfarë mund të bëjë Zentor App?","visitor_id":"<UUID ose ID e gjeneruar nga klienti>"}

Shembull response-i

{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}

Kodet e gabimeve

401 WIDGET_TOKEN_MISSING — Mungon header-i `X-Widget-Token`.
401 WIDGET_TOKEN_INVALID — Token-i i ngulitjes nuk përputhet me kodin e widget-it.
400 VISITOR_ID_REQUIRED — Mungon fusha `visitor_id`.

Sjellja e verifikuar

Një mesazh i vlefshëm kthen 200 me përgjigjen e chatbot-it; një token që mungon ose është i pavlefshëm, si dhe `visitor_id` që mungon, kthejnë kodet e dokumentuara të gabimit.

Widget-i i bisedës

GET /api/public/widget/healthKontroll i thjeshtë i disponueshmërisë së shërbimit të widget-it.GET /api/public/widget/config/:widget_codeKthen konfigurimin publik të një widget-i (emri i shfaqjes, mesazhi i mirëseardhjes, dizajni, gjuha, funksioni i zërit) për inicializim në shfletues.GET /api/public/widget/historyNgarkon historinë e mëparshme të mesazheve të një bisede widget-i, për shembull pas rifreskimit të faqes.POST /api/public/widget/pollMerr mesazhet e marra pas një momenti të caktuar – për shembull përgjigjen e një punonjësi që ka marrë përsipër bisedën.POST /api/public/widget/ratingRuan vlerësimin e vizitorit për një bisedë (e dobishme ose jo e dobishme).POST /api/public/widget/trackRegjistron një ngjarje anonime përdorimi të widget-it (p.sh. „widget-i u hap“) për analizat në panelin e kontrollit.POST /api/public/widget/voice-transcribeShndërron një regjistrim zanor të vizitorit në tekst (hyrje me zë), nëse funksioni i zërit është aktivizuar për widget-in.POST /api/public/widget/voice-speakShndërron tekstin në të folur (dalje me zë në widget), nëse funksioni i zërit është aktivizuar.

Artikuj të lidhur

← Widget-i i bisedës