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-проверкой отправка не повторяется.