# 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](https://webim.ru/kb/dev/api/stored-data/overview.html). ## Метод provide_visitor_fields { #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 использованием токенизатора. !!! Note "N.B." * Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей посетителя (`provided visitor fields`) * Пользовательский интерфейс (фронтенд) внешней системы должен иметь (на страницах своего сайта или в мобильном приложении) следующий Javascript-код: ``` window.webim_auth_token = ; ``` При этом на страницах не должно быть объекта `webim_visitor`, который содержит идентифицирующие данные. Также стоит упомянуть, что при успешном использовании метода у посетителя **не будет** возможности ввести контактную информацию в виджете чата. * Фронтенд внешней системы также должен иметь имплементированным следующий обработчик, обрабатывающий событие прихода ошибки от **Webim Server** `provided_auth_token_not_found`: ``` window.webimHandlers.onProvidedTokenNotFoundError ``` О других обработчиках Webim смотрите [здесь](https://webim.ru/kb/dev/iframe.html). * В момент, когда пользователь выходит из системы (перестает быть авторизованным в системе заказчика), бэкенд организации должен отправить на сервер **Webim** POST-запрос в метод `provide_visitor_fields` с токеном и без `visitor_fields`, при этом комбинация токен-поля в памяти сервера будет удалена, и не сможет использоваться после выхода. Фронтэнд при этом должен прекратить выставлять на страницах `webim_auth_token`. * Функциональность, предоставляемая данным методом, доступна и в тех пользовательских интерфейсах, где виджет чата для посетителей расположен внутри [iframe](https://webim.ru/kb/dev/iframe.html). Также она доступна для мобильных приложений, написанных с использованием **Webim Mobile SDK** (версия от 3.20 и новее). * Если для аккаунта настроена [маршрутизация посетителей](https://webim.ru/kb/for-admins/visitor-routing.html), поля, по которым выполняются правила, должны быть доступны на фронтенде. При использовании `provide_visitor_fields` значения таких полей нужно дополнительно передавать в объекте `window.chat_routing_fields` (см. [описание](https://webim.ru/kb/dev/identification/id-2-0.html#chat-routing-fields)): поля из тела запроса виджету недоступны и в выборе размещения не участвуют. ### Примеры запроса Пример тела запроса: ``` { "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 | Описание ошибки | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `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": "наименование первого ключа, указанного не строкой"
}``` | | `field-value-is-not-string` | В переданных `visitor_fields` имеется значение, указанное не строкой. Полный формат возвращаемого объекта:
```{
"error": "field-value-is-not-string",
"field_value": "первое значение, указанное не строкой"
}``` | * `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**) системы. !!! Note "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 | Описание ошибки | |----------------------------------|----------------------------------------------------------------------------------------------------------------------------| | `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) ## Метод send_broadcast **Метод API**: `send_broadcast` **Итоговый URL**: `https://{hostname}/api/v2/rt/send_broadcast` **Тип запроса**: POST **Query-string параметры**: не нужны **Content-Type**: `application/json` **Формат тела запроса**: JSON Данный метод предназначен для отправки WhatsApp[^whatsapp_footnote] рассылок в **360dialog** и **GupShup**. !!! Note "N.B." Шаблон **WhatsApp** должен быть зарегистрирован и иметь статус `active`. Если номер посетителя не зарегистрирован в **WhatsApp**, то рассылка не придет ему даже при условии установленного приложения. ### Примеры запроса Пример тела запроса для отправки шаблона без параметров: ``` { "operator_id":240557, "data":{ "kind":"whatsapp", "channel_id":"b2ea3fb5620f431a91221e44eb8d656c", "data":{ "template_id":"IXgwY79xu7YZbq5qYofWWT", "entries":[ { "phone_number":"88005553535", "language_code":"ru" } ] } } } ``` !!! Note "N.B." При отправке запроса без указания параметров шаблона, рассылка будет отправлена согласно содержанию шаблона в личном кабинете **360dialog** или **GupShup**. Рассылка может быть текстового формата, а также включать в себя медиафайлы и кнопки. Пример тела запроса с отправкой текстового шаблона: ``` { "operator_id": 240557, "data": { "kind": "whatsapp", "channel_id": "b2ea3fb5620f431a91221e44eb8d656c", "data": { "template_id": "l6A5bDMH0wSkuMVXN0O6WT", "entries": [ { "phone_number": "88005553535", "language_code": "ru", "body": { "parameters": [ { "type": "text", "text": "Здравствуйте, готовы сообщить о нашей новой акции" } ] } } ] } } } ``` Результаты рассылки будут отображаться в интерфейсе рассылок **Webim**. !!! Note "N.B." На текущий момент ввиду технических особенностей отправка медиафайлов, включая аудио, видео и документы, при отправке запроса не поддерживается. Описание входных параметров: | Имя | Тип | Пример | Описание | |---------------|-----------|---------|---------------------------------------------------------------------| | `operator_id` | `Integer` | `96738` | Идентификатор оператора, от имени которого отправляется рассылка | | `data` | `Object` | `{...}` | Данные о рассылке. Содержит параметры `kind`, `channel_id` и `data` | Описание параметров объекта `data`: | Имя | Тип | Пример | Описание | |--------------|----------|------------------------------------|--------------------------------------------------------------------------------------------------------------------| | `kind` | `String` | `whatsapp` | Может принимать следующие значения:
`history-chats` – рассылка по диалогам
`whatsapp` - рассылки в WhatsApp. | | `channel_id` | `String` | `c8da66adc4f3464e838112a14ff5bdc3` | Идентификатор канала общения Webim | | `data` | `Object` | `{...}` | Информация о шаблоне рассылки. Содержит параметры `template_id` и `entries` | Описание параметров объекта `data` (информация о шаблоне рассылки): | Имя | Тип | Пример | Описание | |---------------|--------------------|--------------------------|-----------------------------------------------------------------------------------------------| | `template_id` | `String` | `l6A5bDMH0wSkuMVXN0O6WT` | Идентификатор шаблона, зарегистрированного в WhatsApp | | `entries` | `Array of Objects` | `[...]` | Данные о компонентах рассылки: номер телефона, язык шаблона и содержимое объекта `body` | Описание параметров объекта `entries`: | Имя | Тип | Пример | Описание | |-----------------|--------------------|---------------|--------------------------------------------------------------------------------------| | `phone_number` | `String` | `88005553535` | Номер телефона посетителя | | `language_code` | `String` | `en` | Информация о языке шаблона | | `body` | `Object` | `{...}` | Данные рассылки. Содержит параметр `parameters` | Описание параметров объекта `body`: | Имя | Тип | Пример | Описание | |--------------|--------------------|----------|---------------------------------------------------------------------------| | `type` | `String` | `header` | Может принимать следующие значения: `header`, `body`, `footer` | | `parameters` | `Array of Objects` | `body` | Данные о параметрах `header`, `body`, `footer` | Описание параметров объекта `parameters` для `type:header`: | Имя | Тип | Пример | Описание | |------------|----------|-----------------|-------------------------------------------------------------------------| | `type` | `String` | `text` | Может принимать следующие значения: text, image, video, document, audio | | `text` | `String` | `Здравствуйте!` | Передаваемый текст | Описание параметров объекта `parameters` для `type:body`: | Имя | Тип | Пример | Описание | |--------|----------|----------|--------------------------------------------------------------| | `type` | `String` | `text` | Тип передаваемой информации. Может принимать значение `text` | | `text` | `String` | `Hello!` | Передаваемый текст | Описание параметров объекта `type:footer`: | Имя | Тип | Пример | Описание | |--------|----------|----------|--------------------| | `text` | `String` | `Hello!` | Передаваемый текст | !!! Note "N.B." * Передаваемые параметры должны быть в той же последовательности, что и в шаблоне **WhatsApp**: [Документация по шаблонам **360dialog**](https://docs.360dialog.com/docs/waba-messaging/template-messaging) [Документация по шаблонам **GupShup**](https://docs.gupshup.io/docs/template-messages) ### Возвращаемые значения * `200` – запрос выполнен успешно: ``` { "result": "ok" } ``` * Также код `200` может возвращаться в случаях ошибок обработки предоставленных данных: ``` { "error": "" } ``` * `401` - авторизационные данные отсутствуют или не прошли проверку (`unauthorized`): ``` { "error": "unauthorized" } ``` В таблице ниже представлены возможные ошибки при отправке рассылки: | Имя ошибки | Описание ошибки | |----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| | `request-body-is-not-object` | Неверный формат исходных данных, например, вместо JSON-объекта передано число | | `request-body-is-not-valid-json` | Передан недействительный (`not valid`) JSON-объект | | `missing-argument` | Пропущен обязательный аргумент:
```{ "error": "missing-argument", "argument": "operator_id"}``` | | `parsing-error` | Неверный формат параметров шаблонов | | `unknown-broadcast-kind` | Неверный формат типа рассылки | [^whatsapp_footnote]: WhatsApp принадлежит корпорации Meta, деятельность которой признана экстремистской и запрещена в РФ. --- Источник: https://webim.ru/kb/dev/api/realtime-2.0.html