- Онлайн-консультант Webim
- -
- База знаний
- -
- Для разработчиков
- -
- Webim Custom Channel API
-
-
-
- 01. Обнаружение нового посетителя, ожидающего ответа
- 02. Выбор посетителя сайта из списка и начало диалога
- 03. Набор ответа посетителю, выбор шаблона
- 04. Запрос контактной информации у посетителя
- 05. Отправка файла посетителю
- 06. Кобраузинг
- 07. «Телепортация» пользователей
- 08. Переадресация диалога другому оператору
- 09. Отправка переписки на адрес электронной почты оператора
- 10. Назначение категории посетителю
- 11. Блокировка посетителя
- 12. Вставка гиперссылки в сообщение
- 13. Добавление заметок
- 14. Проверка орфографии
- Agent`s Handbook
- Как включить оповещения в Google Chrome
- Очереди в РМО
- Работа с офлайн-обращениями на РМО
-
- Алгоритмы назначения чатов
- Видимость диалогов
- Вход в систему
- Генератор лидов и автоприглашения
- График работы
- Добавление кнопки Webim в E-mail
- Закрытие диалогов
- Логотип компании в заголовке чата
- Мониторинг активности сотрудников
- Настройка языков
- Общие настройки организации
- Отделы
- Оценки
- Размещения и настройки кнопки на сайте
- Рассылки
- Регистрация операторов и назначение супервизоров
- Системные сообщения
- Список тайм-аутов
- Финансы
- Функции в каналах общения
- Шаблоны ответов
-
- Встраивание административного интерфейса через iframe
- Как узнать версию своего браузера
- Необходимые доступы на сервер
- Необходимые доступы с сервера
- Обработка файлов, загружаемых в чат
- Редактор настроек аккаунта (account config)
- Сетевые конфигурации сервиса Webim
- Системные требования Webim для веб-приложения операторов
- Системные требования Webim для посетителя
- Схемы сетевого размещения серверных компонентов
-
-
-
- Webim Mobile SDK 3.0 для интеграции в мобильные приложения iOS
- Webim Mobile SDK 3.0 для интеграции в мобильные приложения Windows Phone 8.1
- Информация о выпусках (Release notes) – Webim Mobile SDK 3 для Android
- Информация о выпусках (Release notes) – Webim Mobile SDK 3 для iOS
- Справочник по Webim Mobile SDK – SDK для интеграции в мобильные приложения iOS (iPhone/iPad)
- Справочник по Webim Mobile SDK для интеграции в мобильные приложения Android
- Push-уведомления
- Webim Cordova Plugin
-
- Webim CRM postMessage Interface
- Webim Custom Channel API
- Как сделать ссылку кнопкой старта чата
- Маршрутизатор чатов
- Обработчики событий чата
- Процедура установки чата Webim на сайт в iframe
-
Webim Custom Channel API
Описание
Помимо специально разработанных каналов общения, наш сервис также может интегрироваться через универсальный (произвольный) канал с любой системой для передачи сообщений. Это может быть мессенджер (глобальный или Ваш собственный), коммуникатор, чат в социальной сети, SMS и т. д. Данный API позволяет реализовать интеграцию, когда Webim является главным центром маршрутизации, распределения и обработки обращений, а интегрируемая через него вторая система производит первичную обработку обращения и затем передает его Webim среди множества других каналов, подключённых к нам. Требуется лишь, чтобы систему можно было научить передавать нам сообщения на указанный URL в указанном формате и принимать аналогичные сообщения от нас. Так, если Вы представляете крупный банк и у Вас есть другой чат-сервис, Вы можете передавать обращения нам с помощью универсального канала API. Если же ядром маршрутизации и распределения обращений является как раз вторая система, то стоит обратиться к нашим менеджерам, чтобы подыскать решение, подходящее именно Вам.
Для аутентификации запросов используются секретные ключи, которые передаются в каждом сообщении.
Обычно диалог начинает посетитель, у которого возник вопрос. Однако при определённых обстоятельствах оператор может сам инициировать диалог. В частности, это возможно, если до этого оператор уже общался с посетителем. В таком случае, если предыдущий чат был закрыт, диалог отобразится среди прочих в Истории диалогов. Найдя диалог в списке, оператор сможет начать новый чат, воспользовавшись кнопкой Начать чат.
Настройка
Сам канал настраивается в следующем месте интерфейса: Общие настройки —> Каналы общения —> Произвольный (последний в списке). Здесь нужно задать следующие настройки:
- Название канала, которое будут видеть операторы.
- Если у Вас несколько отделов — тот, в который будут поступать обращения через канал.
- Ваш секретный ключ для шифрования передаваемых данных (Вы придумываете эту строку; она может содержать любые символы).
- Адрес сервера (Callback URL) — зависит от Вашего канала. Сервер Webim будет отсылать все изменения (новые сообщения от оператора) в заданном формате на этот адрес.
Что же касается нашего секретного ключа и идентификатора канала, то Вам нужно будет передавать их в полях Ваших запросов (см. ниже).
Метод /l/ch
Данный метод даёт доступ к серверу Webim через универсальный канал по URL, который используется внешним сервисом и является конечной точкой канала связи со стороны посетителя. Метод отправляет запросы на сервер Webim при осуществлении действий посетителем: при наборе текста, отправке сообщений, файлов и т. д.
Base URL: https://<account-domain>
Итоговый URL: https://<account-domain>/l/ch
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Авторизация: как таковой нет (только через секретный ключ)
Запросы к серверу Webim
В теле запроса должен находиться 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, но в таком случае запрос не несёт в себе никакой информации.
Описание параметров
Название параметра | Тип | Пример | Описание | Обязательный |
---|---|---|---|---|
from.id | String | "c906c924-0727-47e8-8dd0-864f00a24eb6" | Канальный идентификатор пользователя — уникальный, формируется на стороне канала и передаётся Webim, фиксируется в Информации о посетителе в поле ID пользователя в канале. | Да |
from.fields | Object | { id: "c906c924-0727-47e8-8dd0-864f00a24eb6", display_name: "Евгений", phone: "+78123855337", email: "support@webim.ru" } |
Опциональный параметр. Список поддерживаемых полей можно найти здесь.
Все значения полей должны быть типа 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. Возможно, запрос был составлен неверно. |
Запросы от Webim на Callback URL
Сервер Webim шлёт POST запрос на указанный в настройках Callback URL.
Запросы могут отправляться при совершении действий и при других событиях на стороне Webim. На данный момент поддерживается только одно действие: передача информации о наборе текста посетителем.
В теле запроса находится 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, но в таком случае запрос не несёт в себе никакой информации.
Описание параметров
Название параметра | Тип | Пример | Описание | Обязательный |
---|---|---|---|---|
to.id | String | "18445032-9358-4c50-91d7-06fe604b76e3" | Канальный идентификатор пользователя. | Да |
action | String | "operator-typing" | Описывает действия. Доступно только единственное значение "operator-typing" (оператор печатает). | Нет |
value | Boolean | True | Для действия operator-typing отправляет True , если оператор печатает, и False , если нет. Если бы поддерживались другие действия, value бы имел значения, соответствующие каждому действию. |
Да |
text | String | "Здравствуйте, чем я могу Вам помочь?" | Любая строка. В каком виде она написана, в таком виде пользователь её и получит. | Нет |
photo | String | "https://webim.ru/img1234.png" | Для фотографий: URL в формате https://somedomain.com/filename.jpg. | Нет |
file | String | "https://webim.ru/agent_handbook.pdf" | Для файлов: URL в формате https://somedomain.com/filename.doc. | Нет |
secret | String | "5fb4f4401b0f4ec0b492bfd0915feb79" | Секретный ключ клиента, задаётся в настройках канала. | Да |
from.name | String | "Иван Петров" | Имя оператора. | Да |
from.id | Int | 148465 | ID оператора в системе Webim. Определить его можно двумя путями:
|
Да |
from.email | String | "operator@mail.ru" | Электронная почта оператора. | Нет |
channel_id | String | "142a171852f34530b4b66f7b0824812c" | ID канала, генерируется на стороне Webim, виден в настройках канала. | Да |
Остальные параметры аналогичны входящим запросам.
Возможные ответы
Сервер Webim ожидает получить в ответ 200 OK, все остальные коды считаются ошибкой.
Примеры запросов к серверу Webim
- Запрос для отправки простого сообщения, без дополнительных полей в запросе. В данном примере оператору покажется простое текстовое сообщение "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 скачает файл по указанной ссылке, проверит его и передаст его оператору в чат.
{ "from": { "id": "c906c924072747e88dd0864f00a24eb6" }, "photo": "https://cuu.su/m12.jpg", "secret": "5fb4f4401b0f4ec0b492bfd0915feb79", "channel_id": "142a171852f34530b4b66f7b0824812c" }
- Запрос для отправки файла. Аналогично отправке изображения.
{ "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://webim.ru/wp-content/uploads/2020/03/image.jpg", "secret": "5fb4f4401b0f4cc0b442ffd0915feb79", "from": { "name": "Ivan N", "id": 125478, "email": "ivan.n@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" }
- Запрос с файлом.
{ "to": { "id": "c906c924072747e88dd0864f00a24eb6" }, "file": "https://webim.ru/l/v/download/159f6150b78843209f867d/file.doc", "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" }