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 смотрите здесь.
В момент, когда пользователь выходит из системы (перестает быть авторизованным в системе заказчика), бэкенд организации должен отправить на сервер Webim POST-запрос в метод provide_visitor_fields с токеном и без visitor_fields, при этом комбинация токен-поля в памяти сервера будет удалена, и не сможет использоваться после выхода. Фронтэнд при этом должен прекратить выставлять на страницах webim_auth_token.
Внимание: функциональность, предоставляемая данным методом, недоступна в пользовательских интерфейсах, где виджет чата для посетителей расположен внтури 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`	{ "id": "a1e29384df", "display_name": "John Bull", "email": "john@webim.ru", "phone": "+7 123 123 123" }	Структура, состоящая из предоставленных полей посетителя (`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` отсутствует обязательный параметр id
`field-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) системы.