- Сервис онлайн-консультирования Webim
- -
- База знаний
- -
- Для разработчиков
- -
- Webim API
- -
- Webim Custom Channel API
-
-
-
- API сервиса Webim
- Webim Mobile SDK и мобильное приложение Webim для посетителя
- Встраивание чата Webim на сайт
- Идентификаторы посетителя
- Интеграция со сторонними сервисами
- Интерфейс виджета чата
- Логика обработки чатов
- Настройка сервиса Webim
- Операторы и РМО
- Отделы в сервисе Webim
- Панель приборов: ответы на вопросы
- Эксплуатация сервиса Webim
- Основные понятия и термины
- Сброс пароля
- Система управления ролями и правами доступа
- Шаг 1. Установка виджета Webim на сайт
- Шаг 2. Начальная настройка сервиса
- Шаг 3. Регистрация оператора
- Шаг 4. Подключение каналов общения
-
-
-
- 01. Обнаружение нового посетителя, ожидающего ответа
- 02. Выбор посетителя сайта из списка и начало диалога
- 03. Набор ответа посетителю, выбор шаблона
- 04. Запрос контактной информации у посетителя
- 05. Отправка файла посетителю
- 06. «Телепортация» пользователей
- 07. Переадресация диалога другому оператору
- 08. Отправка переписки на адрес электронной почты оператора
- 09. Назначение категории посетителю
- 10. Блокировка посетителя
- 11. Вставка гиперссылки в сообщение
- 12. Добавление cкрытых сообщений
- 13. Проверка орфографии
- Agent`s Handbook
- Горячие клавиши в РМО
- Загрузка файлов в диалог
- Исходящие диалоги
- Как включить оповещения в Google Chrome
- Очереди в РМО
- Работа с офлайн-обращениями в РМО
-
- Автоприглашения
- Активность сотрудников
- Алгоритмы назначения чатов
- Видимость диалогов
- Возможности и ограничения Webim в каналах общения
- Вход в систему
- Геолокация посетителей
- График работы
- Добавление кнопки Webim в E-mail
- Закрытие диалогов
- Логотип компании в заголовке чата
- Маршрутизация чатов между операторами и ботами
- Маска телефонного номера
- Настройка языков
- Общие настройки организации
- Ограничения по длине сообщений и полей
- Особенности функционала «Начать чат» в каналах общения
- Отделы
- Оценки
- Переназначение специализированных клавиш управления в РМО
- Приоритетные страницы
- Рассылки
- Регистрация операторов и назначение супервизоров
- Системные сообщения
- Список тайм-аутов
- Финансы
- Шаблоны ответов
-
-
- Встраивание административного интерфейса через iframe
- Горизонтальное масштабирование (кластеризация)
- Интеграция с почтовыми серверами
- Обработка файлов, загружаемых в чат
- Описание сервисных периодов Webim
- Параметры настроек сервера
- Редактор настроек аккаунта (account config)
- Редактор ресурсов
- Сетевые конфигурации сервиса Webim
-
-
-
- Webim Mobile SDK 3.0 для интеграции в мобильные приложения iOS
- Информация о выпусках (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 на сайт в iframe
-
-
-
- Настройка интеграции с Facebook* (для версий до 10.0 включительно)
- Настройка интеграции с Facebook* с помощью приложения Webim
- Настройка интеграции с Instagram* с помощью приложения Webim
- Настройка приложения для интеграции с Facebook* (для версий до 10.0 включительно)
- Создание бизнес-аккаунта в Instagram*
- Создание страницы организации в Facebook*
- Skype
- Telegram
- Viber
- ВКонтакте
- Одноклассники
-
-
Webim Custom Channel API
СОДЕРЖАНИЕ
Описание
Помимо специально разработанных каналов общения, Webim также может интегрироваться через универсальный (произвольный) канал с любой системой для передачи сообщений. Это может быть мессенджер (глобальный или Ваш собственный), коммуникатор, чат в социальной сети, SMS и т. д. Данный API-интерфейс позволяет реализовать интеграцию, когда Webim является главным центром маршрутизации, распределения и обработки обращений, а интегрируемая через него вторая система производит первичную обработку обращения и затем передает его Webim среди множества других каналов, подключённых к бэкенду Webim. Требуется лишь, чтобы систему можно было научить передавать сообщения на указанный URL в указанном формате и принимать сообщения от Webim на callback URL. Так, если Вы представляете крупный банк и у Вас есть другой чат-сервис, Вы можете передавать обращения нам с помощью универсального канала API. Если же ядром маршрутизации и распределения обращений является как раз вторая система, то стоит обратиться к нашим менеджерам, чтобы подыскать решение, подходящее именно Вам.
Для аутентификации запросов используются секретные ключи, которые передаются в каждом сообщении.
Обычно диалог начинает посетитель, у которого возник вопрос. Однако при определённых обстоятельствах оператор может сам инициировать диалог. В частности, это возможно, если до этого оператор уже общался с посетителем. В таком случае, если предыдущий чат был закрыт, диалог отобразится среди прочих в Истории диалогов. Найдя диалог в списке, оператор сможет начать новый чат, воспользовавшись кнопкой Начать чат.
Настройка
- Название канала, которое будут видеть операторы.
- Если у Вас несколько отделов — тот, в который будут поступать обращения через канал.
- Ваш секретный ключ для шифрования передаваемых данных (Вы придумываете эту строку; она может содержать любые символы).
- Адрес сервера (Callback URL) — зависит от Вашего канала. Сервер Webim будет отсылать все изменения (новые сообщения от оператора) в заданном формате на этот адрес.
Что же касается нашего секретного ключа и идентификатора канала, то Вам нужно будет передавать их в полях Ваших запросов (см. ниже).
Метод /l/ch
Метод для оповещения сервера Webim об осуществлении действий со стороны посетителя: при наборе текста, отправке сообщений, файлов и т. д.
Base URL: https://<account-domain>
Итоговый URL: https://<account-domain>/l/ch
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Авторизация: как таковой нет (только через секретный ключ)
Запросы к серверу Webim
{ "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": "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 |
{ "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
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Авторизация: как таковой нет (только через секретный ключ)
В теле запроса находится объект данных в формате 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": "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://webim.ru/img1234.png", "secret": "960c1a9d118a4b86b2e004c9c12c4150", "from": { "name": "Евгений", "id": 148465, "email": "agent@webim.ru" }, "channel_id": "142a171852f34530b4b66f7b0824812c" }
Пример тела запроса (отправка файла оператором):
{ "to":{ "id": "18445032-9358-4c50-91d7-06fe604b76e3" }, "file": "https://webim.ru/agent_handbook.pdf", "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://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" }