POST/api/public/widget/message
Wysyła wiadomość odwiedzającego do chatbota i zwraca jego odpowiedź — centralny punkt końcowy widżetu czatu.
Wyślijcie `widget_code`, `message`, `visitor_id` oraz — od drugiej wiadomości — `session_id` z poprzedniej odpowiedzi. Przy pierwszym wywołaniu nowej rozmowy pozostawcie `session_id` puste lub ustawcie je na `null`. Odpowiedź zawiera w obiekcie `data` `session_id`, tekst odpowiedzi `response` oraz, w razie potrzeby, przyciski (`buttons`), sugestie produktów (`products`) i stan rozmowy (`state`). Nagłówek `X-Widget-Token` z tokenem osadzania oraz `widget_code` są wymagane. Jeśli token jest brak, serwer odpowiada 401 `WIDGET_TOKEN_MISSING`; jeśli jest nieprawidłowy, 401 `WIDGET_TOKEN_INVALID`; wywołania z niezatwierdzonych domen otrzymują 403 `WIDGET_ORIGIN_DENIED`, a dezaktywowany widżet 404 `WIDGET_DISABLED`. Jeśli brakuje `visitor_id`, serwer odpowiada 400 `VISITOR_ID_REQUIRED`. Wywołanie nie jest idempotentne: każde wysłanie tworzy kolejną wiadomość odwiedzającego i kolejną odpowiedź. Blokujcie pole wprowadzania, gdy żądanie jest w toku, i nie powtarzajcie go automatycznie.
Przegląd
Wywołanie: POST /api/public/widget/message. Ten endpoint należy do grupy „Widżet czatu” API Zentor App. Wymaga ważnego tokenu osadzania widżetu. Wywołanie nie jest idempotentne: każde udane wywołanie ponownie uruchamia akcję. Parametry wymagane: widget_code (body), message (body), visitor_id (body). Parametry opcjonalne: session_id (body). Udokumentowane przypadki błędów: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Poniższa przykładowa odpowiedź pokazuje strukturę udanej odpowiedzi w formacie JSON.
Uwierzytelnianie i zabezpieczenia
Token osadzenia widżetu (nagłówek X-Widget-Token) + lista dozwolonych originów
Idempotentny: Nie
Parametry
widget_code(body, string, wymagane)— Kod widżetu z Waszego kodu osadzaniamessage(body, string, wymagane)— Tekst wiadomości odwiedzającegovisitor_id(body, string, wymagane)— ID odwiedzającego generowany przez widżet i zapisywany w przeglądarcesession_id(body, string)— ID sesji z poprzedniej odpowiedzi; puste lub `null` przy pierwszym wywołaniu nowej rozmowyPrzykładowe żądanie
{"widget_code":"...","message":"Cześć, co potrafi Zentor App?","visitor_id":"<UUID lub ID wygenerowany przez klienta>"}Przykładowa odpowiedź
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Kody błędów
401 WIDGET_TOKEN_MISSING — Brakuje nagłówka `X-Widget-Token`.401 WIDGET_TOKEN_INVALID — Token osadzania nie zgadza się z kodem widżetu.400 VISITOR_ID_REQUIRED — Brakuje pola `visitor_id`.Zweryfikowane zachowanie
Prawidłowa wiadomość zwraca 200 z odpowiedzią chatbota; brakujący lub nieprawidłowy token oraz brakujący `visitor_id` zwracają udokumentowane kody błędów.
Widżet czatu
GET /api/public/widget/healthProste sprawdzenie dostępności usługi widżetu.GET /api/public/widget/config/:widget_codeZwraca publiczną konfigurację widżetu (nazwa wyświetlana, powitanie, wygląd, język, funkcja głosowa) do inicjalizacji w przeglądarce.GET /api/public/widget/historyWczytuje wcześniejszą historię wiadomości rozmowy widżetu, na przykład po ponownym wczytaniu strony.POST /api/public/widget/pollPobiera wiadomości otrzymane po określonym momencie — na przykład odpowiedź pracownika, który przejął rozmowę.POST /api/public/widget/ratingZapisuje ocenę odwiedzającego dotyczącą rozmowy (pomocna lub niepomocna).POST /api/public/widget/trackRejestruje anonimowe zdarzenie użycia widżetu (np. „widżet otwarty”) na potrzeby analiz w panelu.POST /api/public/widget/voice-transcribeZamienia nagranie głosowe odwiedzającego na tekst (wprowadzanie głosowe), jeśli funkcja głosowa jest aktywowana dla widżetu.POST /api/public/widget/voice-speakZamienia tekst na mowę (wyjście głosowe w widżecie), jeśli funkcja głosowa jest aktywowana.