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 использованием токенизатора.

NB:

  • Программно-аппаратная часть (бэкенд) внешней системы должна уметь генерировать комбинации токенов и предоставленных полей посетителя (provided visitor fields)
  • Пользовательский интерфейс (фронтенд) внешней системы должен иметь (на страницах своего сайта или в мобильном приложении) следующий Javascript-код:
    window.webim_auth_token = <auth_token>;

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

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

    О других обработчиках Webim смотрите здесь.

  • Внимание: функциональность, предоставляемая данным методом, недоступна в пользовательских интерфейсах, где виджет чата для посетителей расположен внтури 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). NB: названия и значения всех 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 Не указан токен. Полный формат возвращаемого объекта:
                                    {   
                                        "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":"наименование первого ключа (или значения), указанного не строкой"
                                 }
                                

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

NB: на текущий момент в виду технических особенностей не получится вывести оператора из статуса 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 Пропущен обязательный аргумент:
                                        {   
                                            "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)