Доступные методы API (v4)

В данной статье содержится описание всех методов, используемых Stored Data API версии 4.

Выдача списка операторов

Path: /operators

Тип запроса: GET

Query-string параметры: не нужны.

Запрос возвращает массив всех операторов, привязанных к данному аккаунту Webim.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`status`	`String`	`invisible`	Статус оператора. Все возможные значения можно посмотреть в этой статье.
`roles`	`Array of strings`	`admin`	Список ролей оператора. Может принимать значения `operator`, `admin` и `supervisor`.
`created_at`	`String`	`2023-04-20T15:05:42Z`	Дата регистрации оператора в формате `ISO 8601`.
`email`	`String`	`vkovalev@webim.ru`	Email-адрес оператора.
`full_name`	`String`	`Владимир К.`	Полное имя оператора.
`id`	`Integer`	`196458`	Уникальный идентификатор оператора.

Пример ответа (тело ответа имеет стандартный вид вне зависимости от статуса сотрудника):

[
  {
    "status": "online",
    "roles": [
      "admin"
    ],
    "created_at": "2023-04-08T14:10:32Z",
    "email": "mariakolesnikova@webim.ru",
    "full_name": "Мария",
    "id": 192162
  },
  {
    "status": "offline",
    "roles": [
      "operator"
    ],
    "created_at": "2023-07-10T13:17:49Z",
    "email": "ivan_kuznecov@webim.ru",
    "full_name": "Иван К.",
    "id": 193903
  },
  {
    "status": "invisible",
    "roles": [
      "operator"
    ],
    "created_at": "2023-06-16T18:56:32Z",
    "email": "petr_smirnov@webim.ru",
    "full_name": "Пётр",
    "id": 196158
  },
{
    "status": "pre-dinner",
    "roles": [
      "admin"
    ],
    "created_at": "2023-02-28T12:25:45Z",
    "email": "anastasiagolubeva@webim.ru",
    "full_name": "Анастасия",
    "id": 194435
  },
]

Выдача списка отделов

Path: /departments

Тип запроса: GET

Query-string параметры: не нужны.

Запрос возвращает массив отделов, привязанных к данному аккаунту Webim.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`Integer`	`12`	Уникальный идентификатор отдела.
`name`	`String`	`Отдел продаж`	Название отдела.
`order`	`Integer`	`800`	Порядок сортировки отдела.

Пример ответа:

[
   {
      "id": 1,
      "name": "Первый отдел",
      "order": 100
   },
   {
      "id": 2,
      "name": "Второй отдел",
      "order": 200
   }
]

Выдача диалогов за период

Path: /chats

Тип запроса: GET

Query-string параметры: since — см. ниже (под примером).

Возвращает массив диалогов с определённого момента времени.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`Integer` или `String`	`2036`	Уникальный идентификатор чата. Назначается чату при записи в БД. Это тот номер (или `GUID`, который отображается в РМО и в истории диалога).
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата создания чата в формате `ISO 8601`.
`category_ids`	`Array`	`[1, 4, 23]`	Список идентификаторов назначенных чату категорий, см. пункт Классификация чатов. Может быть пустым.
`operator_id`	`Integer`	`181250`	Уникальный идентификатор оператора.
`operator_comment`	`String`	`Оператор Виктор П. добавил комментарий: {текст комментария}`	Сообщение о добавлении оператором комментария к чату. Может принимать значение `NULL`. (Присутствует, если включена соответствующая функция)
`rates`	`Array`	`"rate": 3,"operator_id": 209920,"created_at": "2023-05-13T23:57:01Z"`	Массив данных о выставленных оператору оценках.
`messages`	`Array`	Описание и примеры значений полей ниже.	Массив из сообщений пользователя, которые были отправлены в чат до его появления в РМО (например, с каналов общения).
`state_history`	`Array`	Описание и примеры значений полей можно посмотреть ниже.	Массив данных, описывающий историю состояний чата. Может принимать значение `NULL`.
`visitor`	`String`	`id: "d6123d01de9d4e61b1a5a4a82e451839"`	Данные посетителя. Не может быть пустым. Обязательно должно присутствовать поле `id`. Объект `fields` внутри `visitor` может быть и пустым, однако в этом случае посетитель будет неавторизованным. Если идентифицирующие посетителя данные предоставляются, то передавать их следует точно в соответствии со статьёй об идентификации. Если пользователь неавторизован, то и `visitor-fields-id` не нужен.
`visit_session`	`String`	Описание и примеры значений полей ниже.	Данные о сессии посетителя.
`start_page.url`	`String`	`https://webim.ru`	URL-адрес страницы, с которой пришёл посетитель.
`more_chats_available`	`Boolean`	`true`	Показывает, остались ли ещё незагруженные чаты, так как в ответ на запрос не может быть возвращено более 100 диалогов.
`last_ts`	`String`	`1551278071115810`	Параметр, принимаемый в качестве since при дальнейших вызовах запросов выгрузки чатов.

Описание полей объекта messages в ответе за запрос:

Название параметра	Тип	Пример	Описание
`id`	`String`	`0052a4489cc742c7b4b867a3ed87991e`	Уникальный идентификатор сообщения.
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата отправки сообщения.
`kind`	`String`	`visitor`	Тип сообщения. Это могут разные виды системных сообщений, сообщения оператора или посетителя, отправленные файлы и т. д. Полное описание типов сообщений можно посмотреть в статье.
`message`	`String`	`Здравствуйте! Мне нужна консультация по вашим тарифам.`	Текст сообщения.
`operator_id`	`Integer`	`245875`	Идентификатор оператора, отправившего сообщение.

Если тип сообщения keyboard или keyboard_response, то актуально следующее описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`String`	`0052a4489cc742c7b4b867a3ed87991e`	Уникальный идентификатор сообщения.
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата отправки сообщения.
`kind`	`String`	`keyboard`	Тип сообщения. Полное описание типов сообщений можно посмотреть в статье.
`data`	`String`	`id: "2"buttonId: "3"messageId: "ee310f4073834962867d77bc84bbe9e7"`	Поля для типа сообщений `keyboard`: `buttons` - кнопки для выбора посетителем. Обладает полями `id` и `text`. `response` - выбранная посетителем кнопка. Обладает полями `buttonId` и `messageId`. Может быть `NULL`. `state` - может принимать значения `completed`, `cancelled`, `pending`. Поля для типа сообщений `keyboard_response`: `request` - содержит поле `messageId`. `button` - выбранная посетителем кнопка. Обладает полями `id` и `text`.

Описание полей объекта state_history в ответе на запрос:

Название параметра	Тип	Пример	Описание
`state`	`String`	`chatting`	Наименование состояния чата. Все состояния отображены на Схеме жизненного цикла чата.
`operator_id`	`Integer`	`181509`	Уникальный идентификатор оператора. Может принимать значение `NULL`.
`at`	`String`	`2023-11-18T09:31:09Z`	Дата смены состояния чата.
`department_id`	`Integer`	`6`	Уникальный идентификатор отдела. Может принимать значение `NULL`.

Описание полей объекта visit_session в ответе на запрос:

Название параметра	Тип	Пример	Описание
`ip`	`String`	`31.193.122.170`	IP-адрес устройства посетителя. Может принимать значение `NULL`.
`landing_page.url`	`String`	`https://telegram.org/`	Страница, с которой посетитель начал чат. Может принимать значение `NULL`.

Описание полей объекта rates в ответе на запрос:

Название параметра	Тип	Пример	Описание
`rate`	`Integer`	`5`	Выставленная оператору оценка (от 1 до 5).
`operator_id`	`Integer`	`245896`	Идентификатор оператора, которому поставлена оценка.
`created_at`	`String`	`2023-05-13T23:57:01Z`	Дата выставления оценки в формате `ISO 8601`.

Пример ответа:

{
   "chats": [
      {
         "id": 453,
         "created_at": "2023-04-04T09:14:57Z",
         "category_ids": [23, 48, 1],
         "operator_id": 123,
         "operator_comment": null,
         "rates": [
           {
             "rate": 3,
             "operator_id": 209920,
             "created_at": "2023-05-13T23:57:01Z"
           }
         ],
         "messages": [
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "for_operator",
               "message": "Посетитель открыл окно диалога со страницы"
               "id": "24113c657f254698a3e660c64c4ed6b5"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "info",
               "message": "Пожалуйста, подождите немного."
               "id": "f5eee59b508e47f999d8a373d0362c95"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "events",
               "message": "Оператор Администратор включился в разговор"
               "id": "324090d75f904a3eb04e54b2fc44094b"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "operator_busy",
               "message": "Приносим извинения, оператор отлучился"
               "id": "b1f9c575fc4d4b45b2480a490443a802"
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "file_operator",
               "data": {
                  "guid": "8cdb288",
                  "content_type": "text",
                  "filename": "v.txt"
               },
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "file_visitor",
               "data": {
                  "guid": "81f0488",
                  "content_type": "text",
                  "filename": "v.txt"
               },
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "operator",
               "message": "Здравствуйте! Чем я могу Вам помочь?",
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "contacts_request",
               "message": "Введите, пожалуйста, информацию.",
               "operator_id": 123
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "contacts",
               "message": {
                  "name": "Вася",
                  "phone": "1",
                  "email": "v@webim.ru"
               }
            },
            {
               "created_at": "2023-04-04T09:14:57Z",
               "kind": "visitor",
               "message": "Пока нет, спасибо"
            }
         ],
         "state_history": [
            {
               "state": "queue",
               "operator_id": null,
               "at": "2023-06-10T17:06:22Z",
               "department_id": null
            },
            {
               "state": "queue",
               "operator_id": 3,
               "at": "2023-06-10T17:06:22Z",
               "department_id": null
            },
            {
               "state": "chatting",
               "operator_id": 3,
               "at": "2023-06-10T17:06:28Z",
               "department_id": null
            },
            {
               "state": "queue",
               "operator_id": null,
               "at": "2023-06-10T20:07:04Z",
               "department_id": 2
            }
         ],
         "visitor": {
            "fields": {
               "email": "support@webim.ru",
               "id": "asdf123",
               "icq": "123123123",
               "login": "somelogin",
               "name": "asdf123",
               "phone": "+7 (812) 385-53-37",
               "profile_url": "https://vk.com/id000",
               "site": "https://webim.ru"
            },
            "id": "4d123f6d7143490d966432ccb24403a4"
         },
         "visit_session": {
            "ip": "192.168.1.123",
            "landing_page": {
               "url": "https://webim.ru"
            }
         },
         "start_page": {
            "url": "https://webim.ru/help/api"
         }
      },
      {
         "id": 454,
         "created_at": "2023-04-04T09:15:57Z"
      },
      {
         "id": 455,
         "created_at": "2023-04-04T09:16:57Z"
      }
      ...
   ],
   "more_chats_available": false,
   "last_ts": 1429054006896762
}

В запросе должен быть указан параметр since. В первом запросе передается since=0, в ответе на каждый запрос есть поле last_ts, и в каждом следующем запросе в качестве since должно передаваться значение last_ts из предыдущего. В параметрах since и last_ts значение указывается в микросекундах!

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

Один и тот же диалог может быть получен несколько раз, если с момента, когда он был получен первый раз, в нем происходили какие-либо изменения.

В ответ на запрос истории возвращается за раз не более 100 диалогов. Если поле more_chats_available в ответе имеет значение true, это означает, что на сервере остались новые или изменившиеся диалоги, "не поместившиеся" в это ограничение, и следует сделать еще один запрос с новым значением since для их получения (и повторять это до тех пор, пока more_chats_available не примет значение false).

Выдача диалогов по ID

Path: /chat

Тип запроса: GET

Query-string параметры: id — id диалога.

Возвращает объект chat по его уникальному идентификатору.

Пример запроса:

https://company.webim.ru/api/v4/chat?id=1465

где chat?id={chat_id} вид команды API, а {chat_id} (в примере 1465) — уникальный идентификатор чата, информацию о котором необходимо получить.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`operator_id`	`Integer`	`181250`	Уникальный идентификатор оператора.
`start_page.url`	`String`	`https://webim.ru`	URL-адрес страницы, с которой пришёл посетитель.
`rates`	`Array`	`"rate": 3,"operator_id": 209920,"created_at": "2020-05-13T23:57:01Z"`	Массив данных о выставленных оператору оценках.
`category_ids`	`Array`	`[1, 4, 23]`	Список идентификаторов назначенных чату категорий, см. пункт Классификация чатов. Может быть пустым.
`visitor`	`String`	`id: "d6123d01de9d4e61b1a5a4a82e451839"`	Данные посетителя. Не может быть пустым. Обязательное поле `id`. Объект `fields` внутри `visitor` может быть и пустым, однако в этом случае посетитель будет неавторизованным. Если идентифицирующие посетителя данные предоставляются, то передавать их следует точно в соответствии со статьёй об идентификации. Если пользователь не авторизован, то и `visitor-fields-id` не нужен.
`id`	`Integer` или `String`	`2036`	Уникальный идентификатор чата. Назначается чату при записи в БД. Это тот номер (или `GUID`), который отображается в РМО и в истории диалога.
`operator_comment`	`String`	`Оператор Виктор П. добавил комментарий: {текст комментария}`	Сообщение о добавлении оператором комментария к чату. Может принимать значение `NULL`. (Присутствует, если включена соответствующая функция)
`visit_session`	`String`	Описание и примеры значений полей ниже.	Данные о сессии посетителя.
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата создания чата в формате `ISO 8601`.
`messages`	`Array`	Описание и примеры значений полей ниже.	Массив из сообщений пользователя, которые были отправлены в чат до его появления в РМО (например, с каналов общения).
`state_history`	`Array`	Описание и примеры значений полей можно посмотреть ниже.	Массив данных, описывающий историю состояний чата. Может принимать значение NULL.

Описание полей объекта messages в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`String`	`0052a4489cc742c7b4b867a3ed87991e`	Уникальный идентификатор сообщения.
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата отправки сообщения.
`kind`	`String`	`visitor`	Тип сообщения. Это могут разные виды системных сообщений, сообщения оператора или посетителя, отправленные файлы и т. д. Полное описание типов сообщений можно посмотреть в статье.
`message`	`String`	`Здравствуйте! Мне нужна консультация по вашим тарифам.`	Текст сообщения.

Если тип сообщения keyboard или keyboard_response, то используется следующее описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`String`	`0052a4489cc742c7b4b867a3ed87991e`	Уникальный идентификатор сообщения.
`created_at`	`String`	`2023-11-18T09:29:09Z`	Дата отправки сообщения.
`kind`	`String`	`keyboard`	Тип сообщения. Полное описание типов сообщений можно посмотреть в статье.
`data`	`String`	`id: "2"buttonId: "3"messageId: "ee310f4073834962867d77bc84bbe9e7"`	Поля для типа сообщений `keyboard`: `buttons` - кнопки для выбора посетителем. Обладает полями `id` и `text`. `response` - выбранная посетителем кнопка. Обладает полями `buttonId` и `messageId`. Может быть `NULL`. `state` - может принимать значения `completed`, `cancelled`, `pending`. Поля для типа сообщений `keyboard_response`: `request` - содержит поле `messageId`. `button` - выбранная посетителем кнопка. Обладает полями `id` и `text`.

Описание полей объекта state_history в ответе на запрос:

Название параметра	Тип	Пример	Описание
`state`	`String`	`chatting`	Наименование состояния чата. Все состояния отображены на Схеме жизненного цикла чата.
`operator_id`	`Integer`	`181509`	Уникальный идентификатор оператора. Может принимать значение `NULL`.
`at`	`String`	`2023-11-18T09:31:09Z`	Дата смены состояния чата.
`department_id`	`Integer`	`6`	Уникальный идентификатор отдела. Может принимать значение `NULL`.

Описание полей объекта visit_session в ответе на запрос:

Название параметра	Тип	Пример	Описание
`ip`	`String`	`31.193.122.170`	IP-адрес устройства посетителя. Может принимать значение `NULL`.
`landing_page.url`	`String`	`https://telegram.org/`	Страница, с которой посетитель начал чат. Может принимать значение `NULL`.

Описание полей объекта rates в ответе на запрос:

Название параметра	Тип	Пример	Описание
`rate`	`Integer`	`5`	Выставленная оператору оценка (от 1 до 5).
`operator_id`	`Integer`	`245896`	Идентификатор оператора, которому поставлена оценка.
`created_at`	`String`	`2020-05-13T23:57:01Z`	Дата выставления оценки в формате `ISO 8601`.

Пример ответа:

{
   "chat": {
      "operator_id": 181502,
      "start_page": {
         "url": "https://webim.ru"
      },
      "category_ids": [23, 48, 1],
      "visitor": {
         "fields": {
         },
         "id": "2c4a44b8948e4985951cb6df99279cdc"
      },
      "id": 1465,
      "operator_comment": null,
      "rates": [
        {
          "rate": 3,
          "operator_id": 209920,
          "created_at": "2020-05-13T23:57:01Z"
        }
      ],
      "visit_session": {
         "ip": "31.193.122.170",
         "landing_page": {
            "url": "https://company.webim.ru/sample-page.php?redirected=1"
         }
      },
      "created_at": "2023-07-19T14:39:08Z",
      "messages": [
         {
            "created_at": "2023-07-19T14:39:08Z",
            "message": "Пожалуйста, подождите немного, к Вам присоединится оператор...",
            "kind": "info",
            "id": "24113c657f254698a3e660c64c4ed6b5"
         },
         {
            "created_at": "2023-07-19T14:39:11Z",
            "message": "Привет!",
            "kind": "visitor",
            "id": "f5eee59b508e47f999d8a373d0362c95"
         },
         {
            "created_at": "2023-07-19T14:39:13Z",
            "message": "Оператор Георгий Б включился в разговор",
            "kind": "info",
            "id": "324090d75f904a3eb04e54b2fc44094b"
         },
         {
            "created_at": "2023-07-19T14:39:15Z",
            "operator_id": 181502,
            "message": "Привет и пока!",
            "kind": "operator",
            "id": "b1f9c575fc4d4b45b2480a490443a802"
         },
         {
            "created_at": "2023-07-19T14:39:20Z",
            "message": "Оператор закрыл диалог",
            "kind": "info",
            "id": "2970ed561d6a40c1b788001289096acb"
         }
      ],
      "state_history": [
         {
            "state": "queue",
            "operator_id": null,
            "at": "2023-07-19T14:39:08Z",
            "department_id": 5
         },
         {
            "state": "queue",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:08Z",
            "department_id": 5
         },
         {
            "state": "chatting",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:13Z",
            "department_id": 5
         },
         {
            "state": "closed",
            "operator_id": 181502,
            "at": "2023-07-19T14:39:20Z",
            "department_id": 5
         }
      ]
   }
}

Выдача статистики

Path: /stats

Тип запроса: GET

Query-string параметры: date — дата, за которую запрашивается статистика; mode — usage (обращения различных типов) или operators (отчёт по операторам).

Пример запроса:

https://company.webim.ru/api/v4/stats?date=2023-04-20&mode=usage

Где stats?date={date}&mode={mode} — вид команды API, в котором {date} — дата, статистику за которую необходимо вывести, указанная в формате yyyy-mm-dd, {mode} — режим запроса (usage или operators).

N.B.

Данный эндпоинт в текущей версии возвращает ответ на основе данных модуля Статистики v2. Эти данные могут расходиться с данными, представляемыми модулем Статистики v1. Мы рекомендуем считать верными данные, предоставляемые текущей версией Stored Data API.

Для работы эндпоинта необходимо активировать параметр account config clickhouse_stats!

Статистика по использованию системы

Пример запроса:

{base_url}/api/v4/stats?date=2023-04-20&mode=usage

Запрос возвращает статистику обращений различных типов.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`contacts`	`Integer`	`6`	Общее число обращений за определённую дату.
`missed`	`Integer`	`2`	Количество обращений, ожидающих ответа.
`chats`	`Integer`	`2`	Количество чатов в статусе В диалоге.
`offlines`	`Integer`	`0`	Количество офлайн-обращений.
`avg_waiting_time`	`Float`	`245.0`	Среднее время ожидания.

Пример ответа:

{
    "contacts": 10,
    "missed": 1,
    "chats": 7,
    "offlines": 2,
    "avg_waiting_time": 100.0
}

Статистика по операторам

Пример запроса:

https://company.webim.ru/api/v4/stats?date=2023-04-20&mode=operators

Запрос возвращает отчёт по всем операторам за определённую дату.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`operator_id`	`Integer`	`189650`	Уникальный идентификатор оператора.
`online_time`	`Integer`	`961`	Время оператора в статусе Онлайн.
`chatting_time`	`Integer`	`562`	Время оператора в статусе В диалоге.
`avg_chatting_time`	`Float`	`236.0`	Среднее время оператора в диалоге.
`busy_messages`	`Integer`	`0`	Количество сообщений о занятости оператора, которые отображались пользователям во время обращения к этому оператору.
`chats`	`Integer`	`5`	Количество обработанных обращений.

Пример ответа:

[
    {
        "operator_id": 123,
        "online_time": 28800,
        "chatting_time": 18000,
        "avg_chatting_time": 150.0,
        "busy_messages": 5,
        "chats": 3
    },
    {
        "operator_id": 124,
        "online_time": 23800,
        "chatting_time": 1000,
        "avg_chatting_time": 150.0,
        "busy_messages": 1,
        "chats": 2
    }
]

Выдача списка категорий

Path: /categories

Тип запроса: GET

Query-string параметры: не нужны.

Пример запроса:

https://company.webim.ru/api/v4/categories

Метод возвращает список используемых в системе категорий.

Описание полей объекта в ответе на запрос:

Название параметра	Тип	Пример	Описание
`id`	`Integer`	`1`	Числовой идентификатор категории.
`title`	`String`	`Новая категория`	Наименование категории.
`children`	`Array`	`[{"id": 13,"title": "Новая подкатегория"}]`	Список подкатегорий. Каждый объект массива содержит в себе `id` - идентификатор подкатегории и `title` - наименование подкатегории.

Пример ответа:

[
   {
      "id": 1,
      "title": "New category",
      "children": []
   },
   {
      "id": 2,
      "title": "Новая категория",
      "children": [
         {
            "id": 13,
            "title": "Новая подкатегория"
         }
      ]
   },
   {
      "id": 3,
      "title": "Ещё одна новая категория",
      "children": [
         {
            "id": 11,
            "title": "Ещё одна новая подкатегория"
         }
      ]
   },
   {
      "id": 5,
      "title": "Категория",
      "children": [
         {
            "id": 8,
            "title": "Подкатегория"
         }
      ]
   }
]

Получение загруженного на сервер файла

Path: /file

Тип запроса: GET

Query-string параметры: guid - идентификатор файла. Можно получить из эндпоинта /chat.

Запрос возвращает загруженный на сервер файл.