Перейти к содержанию

Webim Custom Channel API

Webim Custom Channel API связывает Webim с Вашей системой обмена сообщениями. Система передаёт сообщения посетителя на POST /l/ch и принимает события Webim на адрес сервера канала.

Канал создаётся по инструкции «Кастомный канал». В запросах к Webim передаются Идентификатор канала и Наш секретный ключ. В запросах Webim на Ваш сервер передаётся Ваш секретный ключ.

Запрос посетителя

Webim принимает сообщения посетителя методом POST на https://<домен-аккаунта>/l/ch. Параметры в query string не используются.

Заголовок Content-Type должен быть равен строке application/json, без параметров. Проверка выполняется до разбора тела. Значение application/json; charset=utf-8 и любой другой тип получают ответ wrong-content-type.

Состав тела

В теле — один JSON-объект. Обязательны from, secret и channel_id.

Ровно одно из полей text, action, photo, file, location должно быть передано и не быть null. Два таких поля в одном запросе, пустая строка и отсутствие всех пяти полей не проходят проверку.

is_voice к этому списку не относится. Значение true допустимо только вместе с file. Значения false и null без file по этому условию запрос не отклоняют.

Параметры

Параметр Тип Обязательный Описание
from.id Строка, до 64 символов Да Идентификатор посетителя на стороне Вашего канала. Webim хранит его как идентификатор посетителя в канале.
from.fields Объект Нет Дополнительные данные посетителя. Состав — в таблице ниже. Объект можно не передавать.
text Непустая строка Одно из пяти Текст сообщения. Пробелы по краям удаляются. Ограничения длины у этого поля нет. Текст может быть обработан как ответ на опрос или как выбор отдела, а не как отдельное сообщение оператору.
action Непустая строка Одно из пяти Событие посетителя. Обрабатывается значение user-typing.
photo URL Одно из пяти Адрес изображения. Webim скачивает файл по этому адресу.
file URL Одно из пяти Адрес файла, который не передаётся как изображение.
is_voice Логическое значение Нет true помечает file как голосовое сообщение. Запрос отклоняется, только если is_voice истинно, а file нет. false и null без file по этому условию не отклоняются. Без поля и при null рядом с file файл обычный.
location.latitude Число Да, если есть location Широта. Сообщение с геолокацией создаётся при значении от −90 до 90.
location.longitude Число Да, если есть location Долгота. Сообщение с геолокацией создаётся при значении от −180 до 180.
location.user_location Логическое значение Да, если есть location Признак того, что координаты принадлежат самому посетителю. Поле обязательно для проверки запроса и в текст геолокации не входит.
secret Непустая строка, до 64 символов Да Наш секретный ключ из формы канала.
channel_id Строка, до 36 символов Да Идентификатор канала. Это UUID канала.

channel_id длиннее 36 символов не проходит проверку тела. Строка подходящей длины, которая не является UUID, и неизвестный канал дают channel-not-found. В запросах Webim к Вашему серверу идентификатор приходит в каноническом виде с дефисами. На входе принимается и такая форма, и 32 шестнадцатеричных символа без дефисов.

Поля посетителя

from.fields читает только перечисленные ключи. Остальные ключи, включая прежнее поле name, не вызывают ошибку и не используются. Имя посетителя задаёт display_name.

Ключ Описание
display_name Имя посетителя в диалоге. Если в первом сообщении ключа нет, Webim подставляет имя посетителя по умолчанию.
phone Телефон. Строка без отдельной проверки формата.
email Адрес электронной почты. Неверный адрес отклоняет весь запрос.
id Непустая строка до 64 символов. Сохраняется как поле id в данных посетителя, переданных каналом. По непустому значению Webim считает посетителя авторизованным.
client_side_session_id Строка до 64 символов. Сохраняется в данных посетителя. Другого действия в этом API у ключа нет.

Значения — строки. null у отдельного ключа проходит проверку. display_name: null сбрасывает текущее имя; если после этого пусты и имя посетителя, и его имя в канале, Webim записывает имя посетителя по умолчанию. Сам объект from.fields при отсутствии не передавайте как null: опустите поле.

Набор текста посетителем

action со значением user-typing сообщает, что посетитель набирает сообщение. Другие значения action не обрабатываются как отдельные события.

При включённой настройке TRACK_VISITOR_TYPING Webim показывает набор оператору. По умолчанию настройка включена. Повторные события user-typing одного посетителя в одном канале объединяются: в пределах интервала CHANNEL_WEBHOOK_TYPING_THROTTLE_INTERVAL передаётся последнее событие. По умолчанию интервал — одна секунда.

При выключенной TRACK_VISITOR_TYPING запрос user-typing тоже получает result: ok, но индикатор набора не ставится.

Пример: текст

curl --request POST \
  --url 'https://chat.example.local/l/ch' \
  --header 'Content-Type: application/json' \
  --data '{"from":{"id":"visitor-1001","fields":{"display_name":"Евгений","phone":"+78120000000","email":"visitor@example.local"}},"text":"Здравствуйте","secret":"demo-server-secret","channel_id":"142a1718-52f3-4530-b4b6-6f7b0824812c"}'

Тот же JSON:

{
  "from": {
    "id": "visitor-1001",
    "fields": {
      "display_name": "Евгений",
      "phone": "+78120000000",
      "email": "visitor@example.local"
    }
  },
  "text": "Здравствуйте",
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Пример: файл и голосовое сообщение

Обычный файл передаётся полем file. Голосовое сообщение — тот же file и "is_voice": true. Изображение передаётся в поле photo; признак is_voice к нему не добавляется.

{
  "from": {
    "id": "visitor-1001"
  },
  "file": "https://files.example.local/voice.mp3",
  "is_voice": true,
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Пример: геолокация

{
  "from": {
    "id": "visitor-1001"
  },
  "location": {
    "latitude": 59.954908,
    "longitude": 30.29403,
    "user_location": true
  },
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Координаты вне диапазонов из таблицы выше не становятся сообщением посетителя. Если к моменту их обработки есть активный диалог (в том числе созданный этим запросом), Webim может добавить в него служебное сообщение о некорректных координатах. Ответ HTTP при этом остаётся успешным.

Пример: набор текста

{
  "from": {
    "id": "visitor-1001"
  },
  "action": "user-typing",
  "secret": "demo-server-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Ответы на запрос посетителя

Успешный приём:

{
  "result": "ok"
}

Ошибки обработчика канала имеют вид:

{
  "error": "код"
}
Условие HTTP Тело
Запрос принят 200 {"result": "ok"}
Content-Type не равен application/json 200 {"error": "wrong-content-type"}
Корректный JSON-объект не прошёл проверку полей 200 {"error": "internal-error"}
secret не совпал с Нашим секретным ключом 403 {"error": "unauthorized"}
Канал не найден или channel_id не является UUID 404 {"error": "channel-not-found"}
Тело не является синтаксически верным JSON 400 Ответ общего обработчика разбора, не код error из этой таблицы

result: ok означает, что запрос поставлен в обработку. Для файла это происходит до окончания скачивания: ошибка скачивания в этот HTTP-ответ не попадает.

Повторный входящий text может создать в диалоге ещё одно сообщение с тем же текстом.

Посетитель, которому запрещено писать, при корректном запросе тоже получает result: ok. Его сообщение в диалог не добавляется. Не чаще одного раза в сутки Webim отправляет на адрес сервера текст о блокировке, без объекта from. Русский текст ресурса: «Извините, Вам недоступна возможность начинать диалог.» Язык берётся из диалога, а если диалога нет — из языка аккаунта по умолчанию.

Файлы от посетителя

photo и file — адрес, который скачивает сервер Webim. Адрес должен быть доступен этому серверу. Дополнительные HTTP-заголовки для скачивания API не передаёт. Имя файла берётся из последнего сегмента URL. Если в адресе есть query string, его параметры могут попасть в имя файла.

Перед скачиванием файлов по ссылкам из photo и file Webim проверяет адрес. Адреса внутренней сети по умолчанию запрещены; отдельные хосты можно разрешить через SSRF_ALLOWED_HOSTS. Loopback-адреса и адреса метаданных облачных платформ запрещены всегда.

Ответ result: ok приходит до окончания скачивания. Если скачать файл не удалось, в HTTP-ответе ошибки нет: сообщение в диалоге остаётся с ошибкой файла.

На загружаемые файлы действуют ограничения по размеру (MAX_VISITOR_UPLOAD_FILE_SIZE, по умолчанию 10 МБ), расширениям (ALLOWED_UPLOAD_FILE_TYPES) и MIME-типам (ALLOWED_UPLOAD_FILE_CONTENT_TYPES). Значения и списки допустимых типов приведены в настройках файлов. Размер дополнительно ограничивается NGINX_UPLOAD_SIZE. MIME-тип определяется по ответу файлового сервера или содержимому файла.

Ожидание отдачи файла ограничено HTTP_FILE_DOWNLOAD_TIMEOUT.

Запросы Webim на адрес сервера

Webim отправляет POST с телом JSON на Адрес сервера из формы канала и не добавляет к этому адресу собственные query-параметры. Content-Type запроса — application/json.

В каждом запросе есть:

Параметр Тип Описание
to.id Строка from.id посетителя, которому адресовано событие.
secret Строка Ваш секретный ключ.
channel_id Строка UUID канала в каноническом виде, с дефисами.

Объект from есть только когда у события есть автор-оператор. Тогда в нём три поля: name (имя и фамилия), id (числовой идентификатор оператора) и email (адрес оператора, в том числе пустая строка, если адрес не задан). У опроса, текста о блокировке, выбора отдела и информирования автора нет, и объекта from в запросе нет. У набора текста from есть, когда у активного диалога назначен оператор.

Что приходит в теле

Событие Дополнительные поля
Текст оператора text
Изображение, тип содержимого начинается с image/ photo — URL скачивания
Другой файл file — URL скачивания
Голосовое сообщение оператора file и "is_voice": true
Оператор набирает текст action = operator-typing, value — true или false
Вопрос или завершение опроса text и action = survey

Клавиатура, выбор отдела и текст информирования приходят как text: пункты меню пронумерованы и разделены переводом строки. В тексте опроса варианты разделены <br>. У необязательного вопроса к тексту добавляется подсказка, что вопрос можно пропустить. Запрос контактных данных передаётся обычным text. Превью информирования может передаваться текстовой ссылкой.

Служебные сообщения канала уходят как text, если в канале включена отправка информационных сообщений. По умолчанию она выключена.

Отдельного callback о закрытии диалога, изменении сообщения и удалении сообщения нет.

URL вложения имеет вид https://<домен-аккаунта>/l/c/download/<guid>/<имя-файла>?expires=<unix-время>&hash=<подпись>. Ссылка с параметром expires действует ограниченное время.

Длина исходящего text этим запросом не обрезается. Для рассылок в кастомный канал и для поля максимальной длины в состоянии диалога посетителя канал сообщает 4096 символов.

Цитата оператора в этот JSON не входит.

Пример: текст оператора

{
  "to": {
    "id": "visitor-1001"
  },
  "text": "Сейчас уточню информацию.",
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Пример: голосовое сообщение оператора

{
  "to": {
    "id": "visitor-1001"
  },
  "file": "https://chat.example.local/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/voice.mp3?expires=1893456000&hash=demo",
  "is_voice": true,
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Изображение приходит с ключом photo и без is_voice. Обычный файл приходит с ключом file и без is_voice.

Пример: набор текста оператором

{
  "to": {
    "id": "visitor-1001"
  },
  "action": "operator-typing",
  "value": true,
  "secret": "demo-client-secret",
  "from": {
    "name": "Иван Петров",
    "id": 148465,
    "email": "operator@example.local"
  },
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

value: false означает, что оператор перестал набирать текст.

Пример: опрос

{
  "to": {
    "id": "visitor-1001"
  },
  "text": "Оцените консультацию<br><br>1. Отлично<br>2. Хорошо",
  "action": "survey",
  "secret": "demo-client-secret",
  "channel_id": "142a1718-52f3-4530-b4b6-6f7b0824812c"
}

Ответ посетителя на такой текст передаётся обычным входящим text. Webim сопоставляет его с текущим вопросом опроса или с номером отдела, если посетителю предложен выбор отдела.

Ответ Вашего сервера

Успешная доставка — HTTP 200. Любой другой код Webim считает ошибкой доставки.

Повторная отправка выполняется, если Ваш сервер не ответил за HTTP_WEBHOOK_TIMEOUT (по умолчанию 5 секунд), не принял соединение или вернул код 5xx. Тогда тот же callback может прийти ещё раз. Паузы задаёт CHANNEL_OUTBOUND_RETRY_DELAYS_SECONDS: по умолчанию три повтора через 1, 3 и 10 секунд. Подробности — в разделе Тайм-ауты HTTP-запросов каналов.

Ответ 4xx и ответ с перенаправлением повторно не отправляются. По умолчанию адрес сервера, указывающий на внутреннюю сеть, отклоняется при сохранении канала и при отправке. Отдельные внутренние хосты можно разрешить через SSRF_ALLOWED_HOSTS. Loopback и адреса метаданных облачных платформ запрещены всегда. Отклонённая SSRF-проверкой отправка не повторяется.