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 încorporaremessage(body, string, obligatoriu)— Textul mesajului vizitatoruluivisitor_id(body, string, obligatoriu)— ID de vizitator generat de widget și stocat în browsersession_id(body, string)— ID de sesiune din răspunsul anterior; gol sau `null` la primul apel al unei conversații noiExemplu 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ă.