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://<account-domain>
Итоговый URL: https://<account-domain>/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,
      "longtitude": Float,
      "user_location": Boolean
  },
  "secret": String,
  "channel_id": String
}

Предполагается, что в зависимости от содержания запроса присутствует один из пяти параметров: text, action, photo, file или location. В принципе, все эти поля могут быть NULL, но в таком случае запрос не несёт в себе никакой информации.

Параметр запроса secret должен содержать секретный ключ (поле Наш секретный ключ в конфигурации канала), генерируемый на стороне Webim при создании нового кастомного канала.

Параметр запроса channel_id должен содержать идентификатор кастомного канала (поле Идентификатор канала в конфигурации канала), генерируемый на стороне Webim при создании нового кастомного канала.

Пример тела запроса (отправка текстового сообщения):

{
  "from": {
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "text": "Здравствуйте, чем я могу Вам помочь?",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (набор сообщения посетителем):

{
  "from": {
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "action": "user-typing",
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Пример тела запроса (отправка изображения посетителем):

{
  "from": {
    "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
    "fields": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_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": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_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": {
      "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",
      "display_name": "Евгений",
      "phone": "+78121112233",
      "email": "support@webim.ru"
    }
  },
  "location": {
      "latitude": 59.954908,
      "longtitude": 30.294030,
      "user_location": true
  },
  "secret": "960c1a9d118a4b86b2e004c9c12c4150",
  "channel_id": "7638afa6453d45d5b8318d9274880923"
}

Описание параметров

Название параметра	Тип	Пример	Описание	Обязательный
`from.id`	`String`	`c906c924-0727-47e8-8dd0-864f00a24eb6`	Канальный идентификатор пользователя — уникальный, формируется на стороне канала и передаётся Webim, фиксируется в Информации о посетителе в поле ID пользователя в канале.	Да
`from.fields`	`Object`	`{<br> "id": "c906c924-0727-47e8-8dd0-864f00a24eb6",<br> "display_name": "Евгений",<br> "phone": "+78123855337",<br> "email": "support@webim.ru"<br>}`	Опциональный параметр. Список поддерживаемых полей можно найти здесь. Все значения полей должны быть типа `String`, все поля — опциональные.	Нет
`action`	`String`	`user-typing`	Описывает действия. Доступно только единственное значение `user-typing` (пользователь печатает).	Нет
`text`	`String`	`Здравствуйте, чем я могу Вам помочь?`	Любая строка. В каком виде она написана, в таком виде оператор её и получит.	Нет
`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.longtitude`	`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`	Посетитель заблокирован.

Запросы от 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
}

Предполагается, что в зависимости от содержания запроса присутствует один из четырёх параметров: text, action, photo или file. В принципе, все эти поля могут быть NULL, но в таком случае запрос не несёт в себе никакой информации.

Параметр 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`	`Здравствуйте, чем я могу Вам помочь?`	Любая строка. В каком виде она написана, в таком виде пользователь её и получит.	Нет
`photo`	`String`	`https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/photo.png?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a`	Для фотографий: URL в формате `https://somedomain.com/l/c/download/<hash>/<image_name>?expires=<timestamp>&hash=<image_hash>`.	Нет
`file`	`String`	`https://account.webim.ru/l/c/download/aa47f48201d1461fa9c680e9ef92cb78/file.pdf?expires=1701776315&hash=f4bf6b6b26703b65205506d28633c6cd69b66290a1768bf9eddb9096a308b08a`	Для файлов: URL в формате `https://somedomain.com/l/c/download/<hash>/<file_name>?expires=<timestamp>&hash=<file_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, то посетителю будет установлено имя "Иван", также проставится его 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://cuu.su/m12.jpg",
  "secret": "5fb4f4401b0f4ec0b492bfd0915feb79",
  "channel_id": "142a171852f34530b4b66f7b0824812c"
}

Запрос для отправки файла. Аналогично отправке изображения. Если тип контента прикреплённого файла не соответствует одному из типов контента, которые принимает сервер, в ответ на запрос будет возвращена ошибка wrong-file-type.

{
  "from": {
    "id": "c906c924072747e88dd0864f00a24eb6"
  },
  "file": "https://cuu.su/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"
}