# Webim Custom Channel API Помимо специально разработанных каналов общения, **Webim** также может интегрироваться через универсальный (кастомный) канал с любой системой для передачи сообщений. Это может быть мессенджер (глобальный или Ваш собственный), коммуникатор, чат в социальной сети, SMS и т. д. Данный API-интерфейс позволяет реализовать интеграцию, когда **Webim** является главным центром маршрутизации, распределения и обработки обращений, а интегрируемая через него вторая система производит первичную обработку обращения и затем передает его **Webim** среди множества других каналов, подключённых к бэкенду **Webim**. Требуется лишь, чтобы систему можно было научить передавать сообщения на указанный URL в указанном формате и принимать сообщения от **Webim** на callback URL. Так, если Вы представляете крупный банк и у Вас есть другой чат-сервис, Вы можете передавать обращения нам с помощью универсального канала API. Если же ядром маршрутизации и распределения обращений является как раз вторая система, то стоит обратиться к нашим менеджерам, чтобы подыскать решение, подходящее именно Вам. Для аутентификации запросов используются секретные ключи, которые передаются в каждом сообщении. Обычно диалог начинает посетитель, у которого возник вопрос. Однако при определённых обстоятельствах оператор может сам инициировать диалог. В частности, это возможно, если до этого оператор уже общался с посетителем. В таком случае, если предыдущий чат был закрыт, диалог отобразится среди прочих в Истории диалогов. Найдя диалог в списке, оператор сможет начать новый чат, воспользовавшись кнопкой Начать чат. ## Настройка Сам канал настраивается в следующем месте интерфейса: **Общие настройки -> Каналы общения -> Кастомный** (последний в списке). Здесь нужно задать следующие настройки: * **Название канала**, которое будут видеть операторы. * Если у Вас несколько **отделов** — тот, в который будут поступать обращения через канал. * Ваш **секретный ключ** для шифрования передаваемых данных (Вы придумываете эту строку; она может содержать любые символы). * **Адрес сервера (Callback URL)** — зависит от Вашего канала. **Webim Server** будет отсылать все изменения (новые сообщения от оператора) в заданном формате на этот адрес. Что же касается нашего секретного ключа и идентификатора канала, то Вам нужно будет передавать их в полях Ваших запросов (см. ниже). ## Метод /l/ch Данный метод даёт доступ к **Webim Server** через универсальный канал по URL, который используется внешним сервисом и является конечной точкой канала связи со стороны посетителя. Метод для оповещения **Webim Server** об осуществлении действий со стороны посетителя: при наборе текста, отправке сообщений, файлов и т. д. **Base URL**: `https://` **Итоговый URL**: `https:///l/ch` **Тип запроса**: POST **Query-string параметры**: не нужны **Content-Type**: `application/json` **Формат тела запроса**: `JSON` **Авторизация**: параметр запроса `secret` ## Запросы к Webim Server В теле запроса должен находиться `JSON` вида: ``` { "from": { "id": String, "fields": { ... } }, "text": String, "action": String, "photo": String, "file": String, "location": { "latitude": Float, "longitude": Float, "user_location": Boolean }, "secret": String, "channel_id": String } ``` В запросе обязательно должно быть хотя бы одно из следующих полей с непустым содержимым: `text`, `photo`, `file`, `location` или `action`. Пустая строка в `text` не допускается. Если `text` отсутствует или пуст, и при этом не переданы `photo`, `file`, `location` и `action`, сервер возвращает ошибку `invalid-request` (HTTP 400). Параметр запроса `secret` **должен** содержать секретный ключ (поле **Наш секретный ключ** в конфигурации канала), генерируемый на стороне **Webim** при создании нового кастомного канала. Параметр запроса `channel_id` **должен** содержать идентификатор кастомного канала (поле **Идентификатор канала** в конфигурации канала), генерируемый на стороне **Webim** при создании нового кастомного канала. Пример тела запроса (отправка текстового сообщения): ``` { "from": { "id": "c906c924-0727-47e8-8dd0-864f00a24eb6", "fields": { "name": "Евгений", "phone": "+78121112233", "email": "support@webim.ru" } }, "text": "Здравствуйте, чем я могу Вам помочь?", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "channel_id": "7638afa6453d45d5b8318d9274880923" } ``` Пример тела запроса (набор сообщения посетителем): ``` { "from": { "id": "c906c924-0727-47e8-8dd0-864f00a24eb6", "fields": { "name": "Евгений", "phone": "+78121112233", "email": "support@webim.ru" } }, "action": "user-typing", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "channel_id": "7638afa6453d45d5b8318d9274880923" } ``` Пример тела запроса (отправка изображения посетителем): ``` { "from": { "id": "c906c924-0727-47e8-8dd0-864f00a24eb6", "fields": { "name": "Евгений", "phone": "+78121112233", "email": "support@webim.ru" } }, "photo": "https://webim.ru/new_agent.jpg", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "channel_id": "7638afa6453d45d5b8318d9274880923" } ``` Пример тела запроса (отправка файла посетителем): ``` { "from": { "id": "c906c924-0727-47e8-8dd0-864f00a24eb6", "fields": { "name": "Евгений", "phone": "+78121112233", "email": "support@webim.ru" } }, "file": "https://webim.ru/agent_handbook.pdf", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "channel_id": "7638afa6453d45d5b8318d9274880923" } ``` Пример тела запроса (передача геолокации посетителя): ``` { "from": { "id": "c906c924-0727-47e8-8dd0-864f00a24eb6", "fields": { "name": "Евгений", "phone": "+78121112233", "email": "support@webim.ru" } }, "location": { "latitude": 59.954908, "longitude": 30.294030, "user_location": true }, "secret": "960c1a9d118a4b86b2e004c9c12c4150", "channel_id": "7638afa6453d45d5b8318d9274880923" } ``` ### Описание параметров | Название параметра | Тип | Пример | Описание | Обязательный | |--------------------------|-----------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------| | `from.id` | `String` | `c906c924-0727-47e8-8dd0-864f00a24eb6` | Канальный идентификатор пользователя — уникальный, формируется на стороне канала и передаётся **Webim**, фиксируется в **Информации о посетителе** в поле **ID пользователя в канале**. | Да | | `from.fields` | `Object` | `{"name": "Евгений", "phone": "+78123855337", "email": "support@webim.ru"}` | Опциональный объект с данными посетителя. Все переданные ключи (кроме значений `null`) записываются в обычные поля посетителя (`fields`). Для кастомного канала они не копируются в подписанные `provided_fields`, поэтому ключ `id` внутри `from.fields` не делает посетителя авторизованным.

Имя в диалоге и на РМО берётся из `fields.name`.

Значения должны быть строками. Часто используют `name`, `phone`, `email`. | Нет | | `action` | `String` | `user-typing` | Строка. Поддерживается значение `user-typing` для индикации набора текста у посетителя. Может передаваться без `text/photo/file/location`. | Нет | | `text` | `String` | `Здравствуйте, чем я могу Вам помочь?` | Непустая строка. В каком виде передана, в таком виде оператор её и получит. Пустой `text` не допускается: при отсутствии других данных запрос будет отклонён с ошибкой `invalid-request`. | Нет | | `photo` | `String` | `https://webim.ru/new_agent.jpg` | Для фотографий: URL в формате `https://somedomain.com/filename.jpg`. | Нет | | `file` | `String` | `https://webim.ru/agent_handbook.pdf` | Для всех остальных файлов, кроме фото: URL в формате `https://somedomain.com/filename.doc`. | Нет | | `location.latitude` | `Float` | `59.954908` | Значение широты в геолокации, которую передаёт посетитель. | Нет | | `location.longitude` | `Float` | `30.294030` | Значение долготы в геолокации, которую передаёт посетитель. | Нет | | `location.user_location` | `Boolean` | `true` | Свою ли геолокацию передаёт посетитель (`true` — свою, `false` — не свою либо устаревшую). | Нет | | `secret` | `String` | `5fb4f4401b0f4ec0b492bfd0915feb79` | Сгенерированный на стороне **Webim** секретный ключ, виден в настройках канала. | Да | | `channel_id` | `String` | `142a171852f34530b4b66f7b0824812c` | ID канала, генерируется на стороне Webim, виден в настройках канала. | Да | ### Возможные ответы Если неверен секретный ключ, то сервер отдаст код состояния `403`. Если никаких проблем не возникло, сервер отдаст `JSON` вида: ``` { "result": "ok" } ``` Если возникли проблемы, сервер отдаст `JSON` вида: ``` { "error": "код ошибки" } ``` | Код ошибки | Значение | |---------------------------|------------------------------------------------------------------------------------------------------------------------------------| | `wrong-content-type` | Неправильный Content-Type. | | `channel-not-found` | У аккаунта отсутствуют каналы или канал с заданным ID не найден. | | `wrong-file-type` | Неправильный формат файла, возникает при попытке отправить файл с запрещённым расширением. | | `failed-to-download-file` | Прочие сценарии, когда **Webim** не удалось загрузить файл. | | `internal-error` | Внутренняя ошибка **Webim**. Возможно, запрос был составлен неверно. | | `incorrect-image` | Тип контента файла не является `image/*`. | | `max-file-size-exceeded` | Вес загружаемого файла превышает максимальный допустимый размер. | | `user-banned` | Посетитель заблокирован. | | `invalid-request` | В запросе отсутствует содержимое: `text` пустой или отсутствует и одновременно не переданы `photo`, `file`, `location` и `action`. | ## Запросы от Webim на Callback URL **Webim Server** шлёт запросы на указанный в настройках **Callback URL**. Запросы могут отправляться при совершении действий оператором и при других событиях на стороне **Webim**. **Тип запроса**: POST **Query-string параметры**: не нужны **Content-Type**: `application/json` **Формат тела запроса**: `JSON` **Авторизация**: параметр запроса `secret` В теле запроса находится объект данных в формате `JSON` вида: ``` { "to":{ "id": String }, "text": String, "action": String, "photo": String, "file": String, "secret": String, "from": { "name": String, "id": Int, "email": String }, "channel_id": String } ``` Если не передан `action=operator-typing`, то в запросе должно присутствовать хотя бы одно из полей `text`, `photo` или `file`. Пустой `text` не используется. Параметр `secret`, присылаемый сервером **Webim**, можно использовать для авторизации в Вашем канале общения. Параметр `channel_id`, присылаемый сервером **Webim**, можно использовать для идентификации канала общения в Вашем кастомном канале (в тех случаях, когда количество интеграций канала с **Webim** превышает 1). Пример тела запроса (отправка текстового сообщения оператором): ``` { "to":{ "id": "18445032-9358-4c50-91d7-06fe604b76e3" }, "text": "Сейчас уточню информацию по вашему вопросу.", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "from": { "name": "Евгений", "id": 148465, "email": "agent@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Пример тела запроса (набор сообщения оператором): ``` { "to":{ "id": "18445032-9358-4c50-91d7-06fe604b76e3" }, "action": "operator-typing", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "from": { "name": "Евгений", "id": 148465, "email": "agent@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Пример тела запроса (отправка изображения оператором): ``` { "to":{ "id": "18445032-9358-4c50-91d7-06fe604b76e3" }, "photo": "https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/photo.png?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "from": { "name": "Евгений", "id": 148465, "email": "agent@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Пример тела запроса (отправка файла оператором): ``` { "to":{ "id": "18445032-9358-4c50-91d7-06fe604b76e3" }, "file": "https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/file.pdf?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "from": { "name": "Евгений", "id": 148465, "email": "agent@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` ### Описание параметров | Название параметра | Тип | Пример | Описание | Обязательный | |--------------------|-----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------| | `to.id` | `String` | `18445032-9358-4c50-91d7-06fe604b76e3` | Канальный идентификатор пользователя. | Да | | `action` | `String` | `operator-typing` | Описывает действия. Доступно только единственное значение `operator-typing` (оператор печатает). | Нет | | `value` | `Boolean` | `true` | Для действия `operator-typing` отправляет `true`, если оператор печатает, и `false`, если нет. | Да, если присутствует `action` | | `text` | `String` | `Здравствуйте, чем я могу Вам помочь?` | Непустая строка. В каком виде передана, в таком виде пользователь её и получит. Пустой `text` не используется: при передаче статуса набора текста используйте `action=operator-typing` и поле `value`. | Нет | | `photo` | `String` | `https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/photo.png?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a` | Для фотографий: URL в формате `https://somedomain.com/l/c/download//?expires=&hash=`. | Нет | | `file` | `String` | `https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/file.pdf?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a` | Для файлов: URL в формате `https://somedomain.com/l/c/download//?expires=&hash=`. | Нет | | `secret` | `String` | `5fb4f4401b0f4ec0b492bfd0915feb79` | Секретный ключ клиента, задаётся в настройках канала. | Да | | `from.name` | `String` | `Иван Петров` | Имя оператора. | Да | | `from.id` | `Int` | `148465` | ID оператора в системе **Webim**. Определить его можно двумя путями:
  • Запросить список операторов через API
  • Открыть профиль этого оператора и скопировать его id в системе — число в конце URL-адреса открытой страницы. К примеру, если профиль оператора находится по адресу https://companyname.webim.ru/agent/agents/123456, то нужно взять именно число 123456.
| Да | | `from.email` | `String` | `operator@mail.ru` | Электронная почта оператора. | Нет | | `channel_id` | `String` | `142a171852f34530b4b66f7b0824812c` | ID канала, генерируется на стороне **Webim**, виден в настройках канала. | Да | Остальные параметры аналогичны входящим запросам. ### Возможные ответы **Webim Server** ожидает получить в ответ **200 OK**, все остальные коды считаются ошибкой. ## Примеры запросов к Webim Server Запрос для отправки простого сообщения, без дополнительных полей в запросе. В данном примере оператору покажется простое текстовое сообщение `"Hello"`. Поскольку имя клиента не указано в `fields`, то будет использоваться имя посетителя по умолчанию. ``` { "from": { "id": "c906c924072747e88dd0864f00a24eb6" }, "text": "Hello", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос для отправки простого сообщения, с дополнительными полями посетителя в запросе. В данном примере оператору покажется простое текстовое сообщение `"Hello"`. Каждое поле из `fields` записывается в данные посетителя независимо от остальных: из `fields.name` ему будет установлено имя `"Иван"`, из `fields.email` — адрес электронной почты. ``` { "from": { "id": "c906c924072747e88dd0864f00a24eb6", "fields": { "name": "Иван", "email": "ivan.n@webim.com" } }, "text": "Hello with Email.", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос для отправки изображения. **Webim** скачает файл по указанной ссылке, проверит его и передаст его оператору в чат. Если тип контента прикреплённого файла не соответствует одному из типов контента, которые принимает сервер, в ответ на запрос будет возвращена ошибка `incorrect-image`. ``` { "from": { "id": "c906c924072747e88dd0864f00a24eb6" }, "photo": "https://domain.local/m12.jpg", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос для отправки файла. Аналогично отправке изображения. Если тип контента прикреплённого файла не соответствует одному из типов контента, которые принимает сервер, в ответ на запрос будет возвращена ошибка `wrong-file-type`. ``` { "from": { "id": "c906c924072747e88dd0864f00a24eb6" }, "file": "https://domain.local/agreement.doc", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос для действия пользователя. ``` { "from": { "id": "c906c924072747e88dd0864f00a24eb6" }, "action": "user-typing", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` ## Примеры запросов от Webim на Callback URL Запрос с простым сообщением. ``` { "to": { "id": "c906c924072747e88dd0864f00a24eb6" }, "text": "Hello from operator.", "secret": "5fb4f4401b0f4cc0b442ffd0915feb79", "from": { "name": "Ivan N.", "id": 125654, "email": "ivan.n@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос с изображением. ``` { "to": { "id": "c906c924072747e88dd0864f00a24eb6" }, "photo": "https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/image.png?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a", "secret": "5fb4f4401b0f4cc0b442ffd0915feb79", "from": { "name": "Ivan N", "id": 125478, "email": "ivan.n@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос с файлом. ``` { "to": { "id": "c906c924072747e88dd0864f00a24eb6" }, "file": "https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/file.pdf?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a", "secret": "5fb4f4401b0f4cc0b442ffd0915feb79", "from": { "name": "Ivan N.", "id": 126587, "email": "ivan.n@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` Запрос с действием оператора. ``` { "to": { "id": "c906c924072747e88dd0864f00a24eb6" }, "action": "operator-typing", "value": true, "secret": "5fb4f4401b0f4cc0b442ffd0915feb79", "from": { "name": "Ivan N.", "id": 125458, "email": "ivan.n@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" } ``` --- Источник: https://webim.ru/kb/dev/api/custom-channel.html