- Сервис онлайн-консультирования Webim
- -
- База знаний
- -
- Для разработчиков
- -
- Webim API
- -
- Webim Realtime API 2.0
-
-
-
- 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 Realtime API 2.0
СОДЕРЖАНИЕ
Ниже представлена вся необходимая для работы с API информация.
Базовый URL
https://{hostname}/api/v2/rt/{path}
-
{hostname}
– имя сетевого узла (хоста), на котором размещён Webim Server (вида
{account}.webim.ru
для облачных клиентов иchat.mycompany.com
для hosted-клиентов) -
{path}
– команда API
Пример готового запроса к Webim Realtime API:
https://company.webim.ru/api/v2/rt/provide_visitor_fieldsсode>
Авторизация, доступ к API
Метод provide_visitor_fields
provide_visitor_fields
Итоговый URL:
https://{hostname}/api/v2/rt/provide_visitor_fields
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Запрос позволяет провести полнофункциональную авторизацию посетителей (зарегистрированный в Webim вход и выход) из внешней (относительно Webim Server) системы c использованием токенизатора.
NB:
- Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей посетителя (
provided visitor fields
) - Пользовательский интерфейс (фронтенд) внешней системы должен иметь (на страницах своего сайта или в мобильном приложении) следующий Javascript-код:
window.webim_auth_token = <auth_token>;
При этом на страницах не должно быть объекта
webim_visitor
, который содержит идентифицирующие данные (см. здесь).
- Фронтенд внешней системы также должен иметь имплементированным следующий обработчик, обрабатывающий событие прихода ошибки от Webim Server
'provided_auth_token_not_found'
:window.webimHandlers.onProvidedTokenNotFoundError
О других обработчиках Webim смотрите здесь.
- Внимание: функциональность, предоставляемая данным методом, недоступна в пользовательских интерфейсах, где виджет чата для посетителей расположен внтури iframe! При этом функциональность доступна для мобильных приложений, написанных с использованием Webim Mobile SDK (версия от 3.20 и новее).
Примеры запроса
Пример тела запроса:
{ "auth_token": "40bbba7cd1fec39dd1aXXXXXXXXXXX", "visitor_fields": { "id": "a1e29384df", "display_name": "John Bull", "email": "john@webim.ru", "phone": "+7 123 123 123" } }
Пример запроса:
curl --request POST \ --url https://company.webim.ru/api/v2/rt/provide_visitor_fields \ --header 'authorization: Basic dGVzdEB0ZXN0LnXXXXXXXXXXXXXX' \ --header 'content-type: application/json' \ --data '{ "auth_token": "40bbba7cd1fec39dd1aXXXXXXXXXXX", "visitor_fields": { "id": "a1e29384df", "display_name": "John Bull", "email": "john@webim.ru", "phone": "+7 123 123 123" } }'
Поля и форматы параметров запроса:
Имя | Тип | Пример | Описание |
---|---|---|---|
auth_token |
str |
"40bbba7cd1fec39dd1aXXXXXXXXXXX" |
Уникальный, псевдослучайный идентификатор (токен).
Являвется обязательным полем. |
visitor_fields |
Object |
{ "id": "a1e29384df", "display_name": "John Bull", "email": "john@webim.ru", "phone": "+7 123 123 123" } |
Структура, состоящая из предоставленных полей посетителя (provided visitor fields ). NB: названия и значения всех visitor_fields должны быть строками.Необязательное поле.
|
id |
str |
"a1e29384df" |
Идентификатор (provided visitor id ) посетителя в системе организации (важно: отличается от visitor id пользователяв сервисе Webim). Обязательное поле, если присутствует объект |
Остальное | str |
|
Любые персональные данные посетителя, которые нужно передать на сервер. Они в любом случае будут переданы и сохранены в базе данных Webim для данного посетителя. |
Возвращаемые значения
Ниже представлены коды возможных возвращаемых значений и описание к ним.
- 200 – запрос выполнен успешно:
{ "result": "ok" }
Также код 200 может возвращаться в случаях ошибок обработки предоставленных данных:
{ "error": "<error-name>" }
Возможны следующие ошибки:
error-name Описание ошибки auth-token-is-not-string Неверный тип данных в поле токена – например, если он передан числом вместо строк request-body-is-not-object Неверный формат исходных данных – например, вместо JSON-объекта передано число request-body-is-not-valid-json Передан недействительный (not valid) JSON-объект mandatory-field-not-found Не указан токен. Полный формат возвращаемого объекта: { "error":"mandatory-field-not-found", "field":"auth_token" }
id-field-required В переданных visitor_fields
отсутствует обязательный параметрid
field-name-is-not-string В переданных visitor_fields
имеется ключ (или значение), указанный не строкой. Полный формат возвращаемого объекта:{ "error":"field-name-is-not-string", "field_name":"наименование первого ключа (или значения), указанного не строкой" }
- 401 – авторизационные данные отсутствуют или не прошли проверку (unauthorized):
{ "error": "unauthorized" }
- 502 – cервер не готов обработать запрос (Bad Gateway)
Метод agent_status
agent_status
Итоговый URL:
https://{hostname}/api/v2/rt/agent_status
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Данный метод позволяет управлять статусом оператора из внешней (относительно Webim Server) системы.
NB: на текущий момент в виду технических особенностей не получится вывести оператора из статуса offline
.
Примеры запроса
Пример тела запроса:
{ "email": "test@test.ru", "status": "online", "condition": { "initial_statuses": ["dinner", "invisible"] } }
Пример запроса:
curl --request POST \ --url https://company.webim.ru/api/v2/rt/agent_status \ --header 'authorization: Basic dGVzdEB0ZXN0LnXXXXXXXXXXXXXX' \ --header 'content-type: application/json' \ --data '{ "email": "test@test.ru", "status": "online", "condition": { "initial_statuses": ["dinner", "invisible"] } }'
Поля и форматы параметров запроса:
Имя | Тип | Пример | Описание |
---|---|---|---|
email |
str |
"some@bo.dy" |
Почта оператора |
status |
str |
"online" |
Статус, который необходимо выставить оператору |
force |
bool |
true |
Опционально. Необходимо ли принудительно выставить статус оператору, игнорируя ограничения системы |
condition |
dict |
"initial_statuses": ["dinner", "invisible"] |
Опционально. Статусы, в которых должен находиться оператор в настоящий момент |
Возвращаемые значения
- 200 – запрос выполнен успешно:
{ "result": "ok" }
Также код 200 может возвращаться в случаях ошибок обработки предоставленных данных:
{ "error": "<error-name>" }
Возможны следующие ошибки:
error-name Описание ошибки request-body-is-not-valid-json Передан недействительный (not valid) JSON-объект request-body-is-not-object Неверный формат исходных данных - например, вместо JSON-объекта передано число missing-argument Пропущен обязательный аргумент: { "error":"missing-argument", "argument":"email" }
unknown Неизвестная ошибка. Также в текущий момент в виду особенностей системы возвращается, если неверный тип запроса вместо POST condition-not-satisfied Не соблюдены переданные условия перехода оператора в новый статус agent-status-not-allowed Указанный статус не доступен на данном тарифе invalid-agent-email Предоставленная почта оператора не явлется корректной и оператор с такой почтой отсутствует в системе not-in-allowed-online-time Запрещенное время онлайн для операторов (настройка allowed_online_time) - 401 - авторизационные данные отсутствуют или не прошли проверку (unauthorized):
{ "error": "unauthorized" }
- 502 – cервер не готов обработать запрос (Bad Gateway)