Webim Realtime API 2.0

 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

Запрос позволяет провести полнофункциональную авторизацию посетителей (зарегистрированный в 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"
            }
           }'
        

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

                            {
                                "id": "a1e29384df",
                                "display_name": "John Bull",
                                "email": "john@webim.ru",
                                "phone": "+7 123 123 123"
                            }
                            

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

Ниже представлены коды возможных возвращаемых значений и описание к ним.

• 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)

Данный метод позволяет управлять статусом оператора из внешней (относительно 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"]
             }
            }'
        

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

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

• 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)