L2U (`dialog_composer`)

L2U InKnowledge — платформа для управления знаниями и создания сценариев поддержки. Интеграция с Webim позволяет показывать операторам подсказки из сценария L2U во время диалога с посетителем.

Тип L2U связывает Webim с внешним API сценария: ведётся сессия, подсказки приходят по цепочке вызовов /start, /next и /end.

Общие сведения о разделе суфлёров, заголовки запросов и форма создания — на странице Суфлёры. Сравнение с полем сессии в AutoFAQ — в статье про AutoFAQ.

API L2U

Базовый URL

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

Метод

POST

Заголовки

Accept: application/json
Authorization: Bearer {api_token}

/start

Открывает сессию L2U для конкретного чата. Webim вызывает /start один раз перед первым /next, когда для чата впервые нужна подсказка от этого суфлёра.

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

{
  "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

Завершает сессию L2U во внешнем сценарии. Webim вызывает /end, когда чат закрывается или оператор переключает чат на другой суфлёр.

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

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

Поле:

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

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

Для всех трёх путей (/start, /next, /end) нужны HTTP статус 200 и JSON с полем error_code, равным 0 вида:

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

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

Ожидаемые значения error_code:

Код	Значение
`0`	Успешная обработка запроса.
Любое другое целое число	Ошибка на стороне внешнего API. Webim не разбирает такие коды по отдельности и обрабатывает их одинаково как ошибку интеграции.

При ошибке ответа на /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 нет или массив пустой, по этому ответу список подсказок не обновляется.

N.B.

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

L2U (dialog_composer)

API L2U

L2U (`dialog_composer`)