POST/api/public/widget/message

Trimite un mesaj al vizitatorului către chatbot și returnează răspunsul acestuia — endpointul central al widgetului de chat.

Trimiteți `widget_code`, `message`, `visitor_id` și – de la al doilea mesaj – `session_id` din răspunsul anterior. La primul apel al unei conversații noi, lăsați `session_id` gol sau setați-l pe `null`. Răspunsul conține, în obiectul `data`, `session_id`-ul, textul de răspuns `response` și, dacă este cazul, butoane (`buttons`), sugestii de produse (`products`) și starea conversației (`state`). Antetul `X-Widget-Token` cu tokenul de încorporare și `widget_code` sunt obligatorii. Dacă tokenul lipsește, serverul răspunde cu 401 `WIDGET_TOKEN_MISSING`; dacă este invalid, cu 401 `WIDGET_TOKEN_INVALID`; apelurile din domenii neaprobate primesc 403 `WIDGET_ORIGIN_DENIED`, iar un widget dezactivat 404 `WIDGET_DISABLED`. Dacă lipsește `visitor_id`, serverul răspunde cu 400 `VISITOR_ID_REQUIRED`. Apelul nu este idempotent: fiecare trimitere creează un alt mesaj al vizitatorului și un alt răspuns. Blocați introducerea cât timp o cerere este în curs și nu o repetați automat.

Prezentare generală

Apel: POST /api/public/widget/message. Acest endpoint aparține grupului „Widget de chat” al API-ului Zentor App. Necesită un token valid de încorporare a widgetului. Apelul nu este idempotent: fiecare apel reușit declanșează din nou acțiunea. Parametri obligatorii: widget_code (body), message (body), visitor_id (body). Parametri opționali: session_id (body). Cazuri de eroare documentate: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Răspunsul exemplu de mai jos arată structura unui răspuns reușit în format JSON.

Autentificare și securitate

Token de embed pentru widget (header X-Widget-Token) + listă de origini permise

Idempotent: Nu

Parametri

widget_code(body, string, obligatoriu)— Codul widgetului din codul dumneavoastră de încorporare
message(body, string, obligatoriu)— Textul mesajului vizitatorului
visitor_id(body, string, obligatoriu)— ID de vizitator generat de widget și stocat în browser
session_id(body, string)— ID de sesiune din răspunsul anterior; gol sau `null` la primul apel al unei conversații noi

Exemplu de cerere

{"widget_code":"...","message":"Bună, ce poate face Zentor App?","visitor_id":"<UUID sau ID generat de client>"}

Exemplu de răspuns

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

Coduri de eroare

401 WIDGET_TOKEN_MISSING — Antetul `X-Widget-Token` lipsește.
401 WIDGET_TOKEN_INVALID — Tokenul de încorporare nu corespunde codului widgetului.
400 VISITOR_ID_REQUIRED — Câmpul `visitor_id` lipsește.

Comportament verificat

Un mesaj valid returnează 200 cu răspunsul chatbotului; un token lipsă sau invalid, precum și un `visitor_id` lipsă returnează codurile de eroare documentate.

Widget de chat

GET /api/public/widget/healthVerificare simplă a disponibilității serviciului de widget.GET /api/public/widget/config/:widget_codeOferă configurația publică a unui widget (nume afișat, mesaj de bun venit, design, limbă, funcție vocală) pentru inițializarea în browser.GET /api/public/widget/historyÎncarcă istoricul de mesaje anterior al unei conversații de widget, de exemplu după reîncărcarea paginii.POST /api/public/widget/pollObține mesajele primite după un anumit moment — de exemplu răspunsul unui angajat care a preluat conversația.POST /api/public/widget/ratingSalvează evaluarea vizitatorului despre o conversație (utilă sau neutilă).POST /api/public/widget/trackÎnregistrează un eveniment anonim de utilizare a widgetului (de ex. „widget deschis”) pentru analizele din panoul de control.POST /api/public/widget/voice-transcribeConvertește o înregistrare vocală a vizitatorului în text (intrare vocală), dacă funcția vocală este activată pentru widget.POST /api/public/widget/voice-speakConvertește text în vorbire (ieșire vocală în widget), dacă funcția vocală este activată.

Articole similare

← Widget de chat