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) системы.

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)

Метод send_broadcast

Метод API: send_broadcast
Итоговый URL: https://{hostname}/api/v2/rt/send_broadcast
Тип запроса: POST
Query-string параметры: не нужны
Content-Type: application/json
Формат тела запроса: JSON

Данный метод предназначен для отправки WhatsAрp pассылок в 360dialog и GupShup.

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"
            }
         ]
      }
   }
}

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.

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`	`[...]`	Данные о компонентах рассылки: номер телефона, язык шаблона и содержимое объекта `components`

Описание параметров объекта entries:

Имя	Тип	Пример	Описание
`phone_number`	`String`	`88005553535`	Номер телефона посетителя
`language_code`	`String`	`en`	Информация о языке шаблона
`components`	`Array of Objects`	`[...]`	Данные рассылки. Содержит параметры `type` и `parameters`

Описание параметров объекта components:

Имя	Тип	Пример	Описание
`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!`	Передаваемый текст

N.B.

Передаваемые параметры должны быть в той же последовательности, что и в шаблоне WhatsApp:

Документация по шаблонам 360dialog

Документация по шаблонам GupShup

Возвращаемые значения

* `200` – запрос выполнен успешно:

   ```
   {
   "result": "ok"
   }
   ```

* Также код `200` может возвращаться в случаях ошибок обработки предоставленных данных:

 ```
 {
 "error": "<error-name>"
 }
 ```

* `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`	Неверный формат типа рассылки