Перейти к содержанию

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) системы с использованием токенизатора. Поля visitor_fields в этом методе — это предоставленные поля посетителя (provided_fields). Подробнее — в статье Объекты полей посетителя.

N.B.

  • Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей посетителя (provided visitor fields)

  • Пользовательский интерфейс (фронтенд) внешней системы должен иметь (на страницах своего сайта или в мобильном приложении) следующий Javascript-код:

    window.webim_auth_token = <auth_token>;
    

    При этом на страницах не должно быть объекта webim_visitor, который содержит идентифицирующие данные.

    Также стоит упомянуть, что при успешном использовании метода у посетителя не будет возможности ввести контактную информацию в виджете чата.

  • Фронтенд внешней системы также должен иметь имплементированным следующий обработчик, обрабатывающий событие прихода ошибки от Webim Server provided_auth_token_not_found (не работает при установке в iframe):

    window.webimHandlers.onProvidedTokenNotFoundError
    

    О других обработчиках Webim смотрите в описании Webim Visitor JavaScript API.

  • В момент, когда пользователь выходит из системы (перестает быть авторизованным в системе заказчика), бэкенд организации должен отправить на сервер Webim POST-запрос в метод provide_visitor_fields с токеном и без visitor_fields, при этом комбинация токен-поля в памяти сервера будет удалена, и не сможет использоваться после выхода. Фронтэнд при этом должен прекратить выставлять на страницах webim_auth_token.

  • Функциональность, предоставляемая данным методом, доступна и в тех пользовательских интерфейсах, где виджет чата для посетителей расположен внутри iframe. Также она доступна для мобильных приложений, написанных с использованием Webim Mobile SDK (версия от 3.20 и новее).

  • Если для аккаунта настроена маршрутизация посетителей, поля, по которым выполняются правила, должны быть доступны на фронтенде. При использовании provide_visitor_fields значения таких полей нужно дополнительно передавать в объекте window.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>"
    }
    

    Возможны следующие ошибки:

    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>}
    field-value-is-not-string В переданных visitor_fields имеется значение, указанное не строкой. Полный формат возвращаемого объекта:
    {<br> "error": "field-value-is-not-string",<br> "field_value": "первое значение, указанное не строкой"<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

Данный метод предназначен для запуска рассылок: по закрытым диалогам и по шаблонам WhatsApp1 (360Dialog, GupShup).

Примеры запросов

Пример тела запроса для отправки рассылки по закрытым диалогам:

N.B.

Рассылка не отправляется посетителям, у которых в данный момент открыт чат.

{
   "operator_id": 240557,
   "data": {
      "kind": "history-chats",
      "thread_ids": [12345, 12346],
      "message": "Здравствуйте! Мы обновили условия обслуживания."
   }
}

Пример тела запроса для отправки рассылки по шаблону WhatsApp без заданных параметров:

N.B.

При отправке запроса без указания параметров шаблона, рассылка будет отправлена согласно содержанию шаблона в личном кабинете 360dialog или GupShup. Рассылка может быть текстового формата, а также включать в себя медиафайлы и кнопки.

{
   "operator_id":240557,
   "data":{
      "kind":"whatsapp",
      "channel_id":"b2ea3fb5620f431a91221e44eb8d656c",
      "data":{
         "template_id":"IXgwY79xu7YZbq5qYofWWT",
         "entries":[
            {
               "phone_number":"88005553535",
               "language_code":"ru"
            }
         ]
      }
   }
}

Пример тела запроса с отправкой текстового шаблона:

N.B.

Шаблон WhatsApp должен быть зарегистрирован и иметь статус active. Если номер посетителя не зарегистрирован в WhatsApp, то рассылка не придет ему даже при условии установленного приложения.

{
   "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: для history-chats – thread_ids и message, для whatsapp – channel_id и data

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

Имя Тип Пример Описание
kind String whatsapp Может принимать следующие значения:
history-chats – рассылка по закрытым диалогам
whatsapp – рассылка в WhatsApp.
thread_ids Array of Integer [12345, 12346] Идентификаторы диалогов, посетителям которых будет отправлено сообщение. Только для history-chats.
message String Здравствуйте! Текст сообщения рассылки (не более 32000 символов). Только для history-chats.
channel_id String c8da66adc4f3464e838112a14ff5bdc3 Идентификатор канала общения Webim. Только для whatsapp.
data Object {...} Информация о шаблоне рассылки. Содержит параметры template_id и entries. Только для whatsapp.

Описание параметров объекта 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! Передаваемый текст

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-объект
parsing-error Неверный формат данных рассылки или не хватает обязательного поля внутри data. Поле details возвращается только при неизвестном kind: Reason: unknown-kind
no-tariff-option Для данного вида рассылки не подключена тарифная опция
no-operator Передан пустой operator_id или значение 0. Только для history-chats
no-threads Список идентификаторов диалогов thread_ids пуст. Только для history-chats
no-message Текст сообщения message пуст. Только для history-chats
max-message-length-exceeded Превышена максимальная длина сообщения в message (32000 символов). Только для history-chats
visitors-not-found По переданным thread_ids не найдены диалоги. Только для history-chats
channel-not-found Канал с указанным channel_id не найден или отключён. Только для whatsapp
wrong-channel-type Указанный канал не поддерживается для рассылки WhatsApp. Только для whatsapp
template-not-found Шаблон с указанным template_id не найден. Только для whatsapp
channel-api-error Не удалось проверить номера: запрос к 360Dialog или Gupshup завершился ошибкой. Только для whatsapp

  1. WhatsApp принадлежит корпорации Meta, деятельность которой признана экстремистской и запрещена в РФ. ↩