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

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)