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

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

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

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.
categories	Array[Array[String]]	[["Категория", null], ["Категория", "Подкатегория"]]	Массив пар Категория чата - Подкатегория чата, см. пункт Классификация чатов. Массив может быть пустым, значение подкатегории может быть NULL
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",
         "categories": [["Категория", null], ["Категория", "Подкатегория"]],
         "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/v3/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"	Массив данных о выставленных оператору оценках.
categories	Array[Array[String]]	[["Категория", null], ["Категория", "Подкатегория"]]	Массив пар Категория чата - Подкатегория чата, см. пункт Классификация чатов. Массив может быть пустым, значение подкатегории может быть NULL
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"
      },
      "categories": [["Категория", null], ["Категория", "Подкатегория"]],
      "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/v3/stats?date=2023-04-20&mode=usage

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

N.B.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

[
    {
        "operator_id": 123,
        "online_time": 28800,
        "chating_time": 18000,
        "avg_chating_time": 150,
        "busy_messages": 5,
        "chats": 3
    },
    {
        "operator_id": 124,
        "online_time": 23800,
        "chating_time": 1000,
        "avg_chating_time": 150,
        "busy_messages": 1,
        "chats": 2
    }
]

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

Path: /file

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

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

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