Skip to content

Бот-суфлёр

Боты-суфлёры помогают операторам отвечать быстрее с помощью готовых подсказок и сценариев. Поддерживаются два типа: AutoFAQ (набор коротких ответов) и L2U (пошаговые подсказки с сессиями). Все операции с суфлёрами фиксируются в «Истории действий» (создание, обновление, удаление).

Тарифная опция

Начиная с версии 10.8, функция доступна как тарифная опция. Для активации обратитесь к вашему аккаунт-менеджеру или в техническую поддержку Webim. После включения опции раздел появляется в РМО.

Где находится

Путь в РМО: Ассистенты → Суфлёры.

Функционал суфлёров

На странице доступны:

  • селектор «Суфлёр по умолчанию» с кнопкой Применить

  • вкладки Активные суфлёры и Отключённые суфлёры

  • действия для каждой строки: редактировать, отключить/включить, удалить

  • кнопка Создать нового суфлёра

Типы:

  • AutoFAQ (operator_hints) — интеграция с внешним API, которое возвращает варианты коротких ответов. См. API AutoFAQ.
  • L2U (dialog_composer) — интеграция с внешним API сценария, которое ведёт сессию и возвращает подсказки.

Чтобы включить бота-суфлёра, выберите суфлёр по умолчанию и нажмите кнопку «Применить».

Интеграция обработчика

Запросы к обработчику выполняются с заголовками:

Accept: application/json
Authorization: Bearer {api_token}

api_token задаётся в настройках суфлёра и передаётся вашему обработчику.

Эти заголовки используются во всех запросах к API суфлёра ниже (AutoFAQ и L2U).

Ниже описан протокол взаимодействия с API суфлёра для версии Webim 10.8.

API AutoFAQ (operator_hints)

URL

Используется адрес из поля URL в настройках суфлёра (в конфигурации он хранится как api_url), без добавления суффиксов пути.

Метод

POST

Заголовки

Accept: application/json
Authorization: Bearer {api_token}

Тело запроса

{
  "session": "<идентификатор_сессии_чата>",
  "text": "Текст последнего сообщения посетителя"
}

Поля запроса

  • session — идентификатор сессии чата (внутри Webim: chat.session.id).
  • text — текст входящего сообщения посетителя (внутри Webim: message.text).

В L2U то же значение сессии передаётся в поле session_id — это намеренное различие имён между двумя протоколами, а не разные сущности.

Ожидаемый ответ

HTTP 200 и JSON:

{
  "answerVariants": [
    "text1",
    "text2",
    "text3"
  ]
}

Поля ответа

  • answerVariants — массив строк-подсказок.

Webim берёт первые number_of_prompts элементов массива и показывает их оператору.

Если ответ не HTTP 200, тело не удаётся разобрать как JSON или в нём нет ожидаемой структуры, подсказки оператору не показываются; детали ошибки фиксируются в логах сервера Webim.

API L2U (dialog_composer)

Базовый URL

Берётся из поля URL в настройках суфлёра (api_url); к нему добавляются пути /start, /next и /end.

Метод

POST

Заголовки

Accept: application/json
Authorization: Bearer {api_token}

/start

Тело запроса:

{
  "channel_id": "1458",
  "session_id": "<id_сессии_чата>",
  "user_id": "<id_посетителя>"
}

Поля:

  • channel_id — идентификатор чата в Webim (chat.id). В JSON он передаётся строкой, даже если в системе id числовой (пример: "channel_id": "1458").
  • session_id — идентификатор сессии чата, строка (chat.session.id).
  • user_id — идентификатор посетителя, строка (chat.session.visitor.id).

Пока вызов /start для чата не завершился успешно, /next не отправляется: при первом подходящем сообщении посетителя сначала вызывается /start, и только после успеха — /next с тем же содержимым сообщения.

/next

Для обычного сообщения:

{
  "content": "Текст сообщения посетителя",
  "content_type": "text",
  "session_id": "<id_сессии_чата>"
}

Для нажатия кнопки:

{
  "content": "<id_нажатой_кнопки>",
  "content_type": "text",
  "session_id": "<id_сессии_чата>"
}

Поля:

  • content — текст сообщения посетителя или идентификатор нажатой кнопки.
  • content_type — в текущей реализации всегда строка text и для текста, и для кнопки: отдельного поля «тип события» в запросе нет, так устроен протокол Webim. Отличить нажатие кнопки от обычного текста на стороне вашего API нужно самостоятельно: в content приходит либо произвольный текст сообщения, либо тот же строковый id кнопки, что задан в разметке исходного сообщения в Webim (ориентируйтесь на известный набор id в сценарии или на соглашения о формате id).
  • session_id — ID сессии чата, строка.

/end

Тело запроса:

{
  "session_id": "<id_сессии_чата>"
}

Поле:

  • session_id — идентификатор сессии чата, строка.

Ожидаемый ответ для L2U

Для всех трёх путей (/start, /next, /end) нужны HTTP 200 и JSON с полем error_code, равным 0. Любой другой HTTP-код, невалидный JSON или error_code, отличный от 0, обрабатываются как ошибка интеграции: подсказки оператору не обновляются; при ошибке на /start сессия суфлёра для чата не считается начатой; при ошибке на /next текущие подсказки сбрасываются.

При ошибке ответа на /end сведения записываются в логи сервера Webim; повторного автоматического вызова /end не выполняется. Чтобы корректно завершить сценарий на стороне вашего API (освободить ресурсы сессии и т. п.), рекомендуется отвечать на /end успешно (HTTP 200, error_code: 0).

На /start и /end достаточно минимального успешного тела, например:

{
  "error_code": 0
}

Ответы на эти два вызова Webim не использует для заполнения списка подсказок (важен только успешный статус и error_code).

На /next в успешном ответе передают подсказки в массиве messages:

{
  "error_code": 0,
  "messages": [
    { "content": "text1" },
    { "content": "text2" },
    { "content": "text3" }
  ]
}

Поля ответа

  • error_code — целое число; 0 — успех, иное значение — ошибка интеграции.
  • messages — массив объектов подсказок (актуален для /next).
  • messages[].content — текст подсказки.

Webim берёт первые number_of_prompts элементов messages на /next и использует content как текст подсказки оператору. Если messages нет или массив пустой, по этому ответу список подсказок не обновляется.

Создание нового суфлёра

Нажмите Создать нового суфлёра и заполните форму:

Поля формы

  • Имя — внутреннее название.
  • Тип — AutoFAQ или L2U.
  • URL — адрес вашего обработчика подсказок (HTTP/HTTPS); в разделе «Интеграция обработчика» выше это же значение называется api_url.
  • Токен — строка авторизации для заголовка Authorization.
  • Количество подсказок — максимальное число подсказок на один запрос/отображение.

Примеры ответов API

  • AutoFAQ:
{
  "answerVariants": ["text1", "text2", "text3", "text4"]
}
  • L2U:
{
  "error_code": 0,
  "messages": [
    { "content": "text1" },
    { "content": "text2" },
    { "content": "text3" },
    { "content": "text4" }
  ]
}

N.B.

Для L2U при подключении к диалогу автоматически создаётся сессия; при закрытии диалога или переключении на другой суфлёр текущая сессия завершается.

Суфлёры стандартизируют ответы и ускоряют работу операторов. Подключите опцию, создайте подходящий тип (AutoFAQ или L2U), настройте обработчик и при необходимости назначьте суфлёр по умолчанию.

Последнее обновление страницы: 1 апреля 2026 г.