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Перетворює текст на вимовлену мову (голосовий вивід у віджеті), якщо голосову функцію активовано.

Споріднені статті

← Чат-віджет