Webim Realtime API 2.0
Webim Realtime API создан для взаимодействия с сервером чатов в реальном времени из внешних (относительно Webim Server) систем. В настоящий момент времени является актуальной версией API.
Ниже представлена вся необходимая для работы с API информация.
Базовый URL
Базовый 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
Авторизация, доступ к API
Авторизация идентична той, что используется в Stored Data API.
Метод provide_visitor_fields
Метод API: provide_visitor_fields
Итоговый URL: https://{hostname}/api/v2/rt/provide_visitor_fields
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Запрос позволяет провести полнофункциональную авторизацию посетителей (зарегистрированный в Webim вход и выход) из внешней (относительно Webim Server) системы c использованием токенизатора.
N.B.
-
Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей посетителя (
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 |
Уникальный, псевдослучайный идентификатор (токен). Является обязательным полем. auth_token может быть любой строкой - например, UUID , но не ограничиваясь им. |
visitor_fields |
Object |
{ |
Структура, состоящая из предоставленных полей посетителя (provided visitor fields ). Названия и значения всех visitor_fields должны быть строками.Необязательное поле.
|
id |
str |
a1e29384df |
Идентификатор (provided visitor id ) посетителя в системе организации (важно: отличается от visitor id пользователя в сервисе Webim).Обязательное поле, если присутствует объект visitor_fields . Должно быть уникальным и непустым. |
Остальное | 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
Не указан токен. Полный формат возвращаемого объекта: {<br> "error": "mandatory-field-not-found",<br> "field": "auth_token"<br>}
id-field-required
В переданных visitor_fields
отсутствует обязательный параметр idfield-name-is-not-string
В переданных visitor_fields
имеется ключ (или значение), указанный не строкой. Полный формат возвращаемого объекта:{<br> "error": "field-name-is-not-string",<br> "field_name": "наименование первого ключа (или значения), указанного не строкой"<br>}
-
401
– авторизационные данные отсутствуют или не прошли проверку (unauthorized
):{ "error": "unauthorized" }
-
502
– cервер не готов обработать запрос (Bad Gateway
)
Метод agent_status
Метод API: agent_status
Итоговый URL: https://{hostname}/api/v2/rt/agent_status
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON
Данный метод позволяет управлять статусом оператора из внешней (относительно Webim Server) системы.
N.B.
На текущий момент в виду технических особенностей не получится вывести оператора из статуса 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
Пропущен обязательный аргумент: {<br> "error": "missing-argument",<br> "argument": "email"<br>}
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)