POST/api/public/widget/message
Надсилає повідомлення відвідувача чат-боту і повертає його відповідь — центральний кінцевий пункт чат-віджета.
Надішліть `widget_code`, `message`, `visitor_id` і — починаючи з другого повідомлення — `session_id` з попередньої відповіді. При першому викликі нової розмови залиште `session_id` порожнім або встановіть `null`. Відповідь містить в об’єкті `data` `session_id`, текст відповіді `response`, а також, за потреби, кнопки (`buttons`), пропозиції товарів (`products`) і стан розмови (`state`). Заголовок `X-Widget-Token` з embed-токеном і `widget_code` обов’язкові. Якщо токен відсутній, сервер відповідає кодом 401 `WIDGET_TOKEN_MISSING`, якщо недійсний — 401 `WIDGET_TOKEN_INVALID`; виклики з незареєстрованих доменів отримують 403 `WIDGET_ORIGIN_DENIED`, деактивований віджет — 404 `WIDGET_DISABLED`. Якщо відсутній `visitor_id`, сервер відповідає кодом 400 `VISITOR_ID_REQUIRED`. Виклик не ідемпотентний: кожне надсилання створює ще одне повідомлення відвідувача та ще одну відповідь. Блокуйте введення, поки запит виконується, і не повторюйте його автоматично.
Огляд
Виклик: POST /api/public/widget/message. Цей ендпоінт належить до групи «Чат-віджет» API Zentor App. Потрібен дійсний embed-токен віджета. Виклик не ідемпотентний: кожен успішний виклик знову запускає дію. Обов’язкові параметри: widget_code (тіло), message (тіло), visitor_id (тіло). Необов’язкові параметри: session_id (тіло). Задокументовані випадки помилок: 401 WIDGET_TOKEN_MISSING, 401 WIDGET_TOKEN_INVALID, 400 VISITOR_ID_REQUIRED. Приклад відповіді нижче показує структуру успішної відповіді у форматі JSON.
Автентифікація та захист
Widget-Embed-Token (заголовок X-Widget-Token) + список дозволених Origin
Ідемпотентний: Ні
Параметри
widget_code(body, string, обов'язково)— Код віджета з вашого коду вбудовуванняmessage(body, string, обов'язково)— Текст повідомлення відвідувачаvisitor_id(body, string, обов'язково)— ID відвідувача, який створює і зберігає віджет у браузеріsession_id(body, string)— ID сесії з попередньої відповіді; при першому викликі нової розмови порожньо або `null`Приклад запиту
{"widget_code":"...","message":"Вітаємо, що вміє Zentor App?","visitor_id":"<UUID або ID, згенерований клієнтом>"}Приклад відповіді
{"ok":true,"data":{"session_id":"31b1096c-a366-4418-b4be-bd999ff98134","response":"...","buttons":[],"state":"idle","products":[]}}Коди помилок
401 WIDGET_TOKEN_MISSING — Відсутній заголовок `X-Widget-Token`.401 WIDGET_TOKEN_INVALID — Embed-токен не відповідає коду віджета.400 VISITOR_ID_REQUIRED — Відсутнє поле `visitor_id`.Перевірена поведінка
Дійсне повідомлення повертає 200 з відповіддю чат-бота; відсутній або недійсний токен, а також відсутній `visitor_id` повертають документовані коди помилок.
Чат-віджет
GET /api/public/widget/healthПроста перевірка доступності сервісу віджета.GET /api/public/widget/config/:widget_codeПовертає публічну конфігурацію віджета (ім’я для показу, текст привітання, дизайн, мову, голосову функцію) для ініціалізації в браузері.GET /api/public/widget/historyЗавантажує попередню історію повідомлень конверсації віджета, наприклад після перезавантаження сторінки.POST /api/public/widget/pollЗапитує повідомлення, що надійшли після певного моменту часу — наприклад, відповідь співробітника, який прийняв розмову.POST /api/public/widget/ratingЗберігає оцінку відвідувача для розмови (корисно або некорисно).POST /api/public/widget/trackФіксує анонімну подію використання віджета (наприклад, «віджет відкрито») для аналізу в панелі керування.POST /api/public/widget/voice-transcribeПеретворює голосовий запис відвідувача в текст (голосове введення), якщо для віджета активовано голосову функцію.POST /api/public/widget/voice-speakПеретворює текст на вимовлену мову (голосовий вивід у віджеті), якщо голосову функцію активовано.