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.
Аутентификация и защита
Токен встраивания виджета (заголовок 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Преобразует текст в произнесённую речь (голосовой вывод в виджете), если голосовая функция активирована.