Omni API — Статистика

OMNIDESK API

Статистика

Лучшие в команде

GET  |  https://[domain].omnidesk.ru/api/stats_leaderboard.json

Данные из подраздела статистики «Лучшие в команде» аккаунта администратора.

Период

1) Если в аккаунте администратора вы обычно смотрите статистику за стандартные периоды, через API есть смысл делать то же самое, используя параметр period. В этом случае не нужно каждый раз определять подходящий timestamp и бескопоиться о том, что данные могут не совпасть с теми, которые администратор видит в своём аккаунте.

2) При получении данных за кастомный период с помощью параметров from_time и to_time минимальный период, который можно задать, составляет 1 час, а максимальный — 3 месяца. В ответ на запрос, в котором задан слишком маленький или слишком большой период, возвращается ошибка.

Кеширование

Обращений, сотрудников и статистических показателей, которые нужно по ним рассчитать, может быть очень много. Поэтому каждый запрос в адрес этого метода не приводит к тому, что Омнидеск заново пересчитывает все данные. В зависимости от заданного периода используется кеш, который хранится определённое время:

last_24_hours — кеш на 5 минут;
last_7_days — кеш на час;
last_14_days — кеш на час;
last_30_days — кеш на день;
today — кеш 5 минут;
yesterday — кеш на день;
this_week — кеш на день;
last_week — кеш на неделю;
this_month — кеш на день;
last_month — кеш на месяц;
month_2 (если сейчас 11.2023, будет 09.2023) — кеш на месяц;
month_3 (если сейчас 11.2023, будет 08.2023) — кеш на месяц;
month_4 (если сейчас 11.2023, будет 07.2023) — кеш на месяц;
month_5 (если сейчас 11.2023, будет 06.2023) — кеш на месяц;
month_6 (если сейчас 11.2023, будет 05.2023) — кеш на месяц;
3_previous_months (три предыдущих, исключая текущий) — кеш на месяц;
6_previous_months (шесть предыдущих, исключая текущий) — кеш на месяц;
this_year — кеш на день;
last_year — кеш на год;
кастомный период от часа до одного дня — кеш на час;
кастомный период от одного дня — кеш на день.

К примеру, если вы хотите получать актуальные данные за сегодня, чтобы отображать график в админке вашего сервиса, можно каждые 5-10 минут выполнять один запрос в адрес этого метода с параметром period=today. Выполнять их чаще нет смысла, так как вы будете получать закешированные данные.

Параметры

period *;string;Выбор одного из стандартных периодов для получения статистических данных. ;;Если используется этот параметр, то параметры «from_time» и «to_time» передавать не нужно, так как они предназначены для указания кастомного периода. ;;Возможные варианты: last_24_hours, last_7_days, last_14_days, last_30_days, today, yesterday, this_week, last_week, this_month, last_month, month_2 (если сейчас 11.2023, будет 09.2023), month_3 (если сейчас 11.2023, будет 08.2023), month_4 (если сейчас 11.2023, будет 07.2023), month_5 (если сейчас 11.2023, будет 06.2023), month_6 (если сейчас 11.2023, будет 05.2023), 3_previous_months (три предыдущих, исключая текущий), 6_previous_months (шесть предыдущих, исключая текущий), this_year, last_year. ;;При расчёте данных используется часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». from_time *;string;Начало периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 00:00:00), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 00:00:00 +0400). to_time *;string;Конец периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 23:59:59), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 23:59:59 +0400). group_id;array / number;ID группы (выборка всех обращений, в которых выставлена данная группа) channel;array / string;Канал обращения. ;;Возможные варианты: email, web, call, live_chat (онлайн-чат), facebook, fb_chat, vkontakte, vk_chat, twitter, instagram_posts, instagram_chat, ok_chat, telegram, skype, slack, mattermost, viber, line, zalo, wa_chat (WhatsApp), youscan, avito, idea, cch123 (кастомный канал), sync (все синхронные каналы), async (все асинхронные каналы), social (соцсети), messengers (мессенджеры). status;array / string;Статус обращения (возможные варианты: open, waiting, closed). priority;array / string;Приоритет обращения (возможные варианты: low, normal, high, critical). staff_id;array / number;ID сотрудника (выборка показателей по обращениям, в которых указанный сотрудник является ответственным). ;;Выставите значение all, если хотите получить данные по всем ответственным. assignee_role_id;array / number;ID роли ответственных сотрудников (выборка показателей по обращениям, в которых сотрудники с указанной ролью являются ответственными). participant_id;array / number;ID сотрудника (выборка показателей по обращениям, в которых указанный сотрудник является участником). ;;Выставите значение all, если хотите получить данные по всем участникам. participant_role_id ;array / number;ID роли сотрудников, которые являются участниками (выборка показателей по обращениям, в которых сотрудники с указанной ролью являются участниками). labels;array;Метки обращений (выборка показателей по обращениям, в которых выставлены определённые метки). initiator;string;Инициатор обращения (возможные варианты: user, agent). user_id;array / number;ID пользователя (выборка показателей по обращениям конкретного пользователя). company_id;array / number;ID компании (выборка показателей по обращениям от пользователей конкретной компании). custom_fields;array;Дополнительные поля данных. Фильтровать можно как по полям обращения, так и по полям пользователя. ;;Для фильтрацию по кастомному полю обязательно нужно указать его ID и значение. В зависимости от типа поля, по которому выполняется фильтрация обращений, поиск осуществляется по-разному: ;;▸ «текстовое поле» или «текстовая область» — производится поиск включения передаваемой строки (custom_fields[cf_7604]=text); ;;▸ «чекбокс» — производится поиск по наличию/отсутствию флага в зависимости от передаваемого значения (custom_fields[cf_7605]=0 или custom_fields[cf_7605]=1); ;;▸ «список» — производится поиск по ключу, равному передаваемому значению (custom_fields[cf_7606]=1, custom_fields[cf_7606]=3 и т. д.); ;;▸ «дата» — производится поиск по ключу, равному передаваемому значению (custom_fields[cf_7607]=2023-06-01 или custom_fields[cf_7607]=1685563200).

Ответ

{
    "0": {
        "staff": {
            "staff_id": 42047,
            "staff_name": "John Snow",
            "new_cases_in_total": 21,
            "new_user_cases": 20,
            "reopened_cases": 2,
            "cases_being_handled": 25,
            "cases_with_a_response": 21,
            "first_response_time": 28, // в секундах
            "first_response_sla_violated": "0%", // SLA первого ответа был соблюдён
            "response_time": 49, // в секундах
            "response_sla_violated": "0%", // SLA любого ответа был соблюдён
            "response_writing_time": 19, // в секундах
            "total_number_of_responses": 29,
            "total_number_of_notes": 8,
            "number_of_responses_for_resolution": 2,
            "closed_cases": 19,
            "resolution_time": 516, // в секундах
            "resolution_sla_violated": "0%", // SLA закрытия был соблюдён
            "ratings_of_responses": "-" // не было оценок
        }
    },
    "1": {
        "staff": {
            "staff_id": 50482,
            "staff_name": "Jack Sparrow",
            "new_cases_in_total": 58,
            "new_user_cases": 57,
            "reopened_cases": 7,
            "cases_being_handled": 103,
            "cases_with_a_response": 64,
            "first_response_time": 97,
            "first_response_sla_violated": "0%",
            "response_time": 80,
            "response_sla_violated": "0.9%",
            "response_writing_time": 38,
            "total_number_of_responses": 202,
            "total_number_of_notes": 18,
            "number_of_responses_for_resolution": 3,
            "closed_cases": 73,
            "resolution_time": 825,
            "resolution_sla_violated": "21.9%",
            "ratings_of_responses": "72%"
        }
    }
}

Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET "https://[domain].omnidesk.ru/api/stats_leaderboard.json?period=this_month&channel=telegram&status=open&group_id=25403&priority=high&staff_id=all&labels=7152&initiator=user&user_id[]=2414276&user_id[]=2414389&company_id=74105&custom_fields[cf_7589]=0&custom_fields[cf_8621]=5

Статусы сотрудников

GET  |  https://[domain].omnidesk.ru/api/stats_staff_statuses.json

Получение статистики по статусам сотрудников.

Период

1) Если в аккаунте администратора вы обычно смотрите статистику за стандартные периоды, через API есть смысл делать то же самое, используя параметр period. В этом случае не нужно каждый раз определять подходящий timestamp и беспокоиться о том, что данные могут не совпасть с теми, которые администратор видит в своём аккаунте.

2) При получении данных за кастомный период с помощью параметров from_time и to_time минимальный период, который можно задать, составляет 1 час, а максимальный — 1 месяц. В ответ на запрос, в котором задан слишком маленький или слишком большой период, возвращается ошибка.

Постраничная навигация

В одном ответе передаётся 100 изменений статуса. Если за выбранный период их было больше, для просмотра следующей страницы со следующими 100 изменениями, передавайте параметр page.

Факт наличия следующей страницы можно узнать по параметру last_page=true/false, который есть в конце каждого ответа. Если last_page=true, значит, вы дошли до последней страницы.

Параметры

period *;string;Выбор одного из стандартных периодов для получения статистических данных. ;;Если используется этот параметр, то параметры «from_time» и «to_time» передавать не нужно, так как они предназначены для указания кастомного периода. ;;Возможные варианты: last_24_hours, last_7_days, last_14_days, last_30_days, today, yesterday, this_week, last_week, this_month, last_month. ;;При расчёте данных используется часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». from_time *;string;Начало периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 00:00:00), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 00:00:00 +0400). to_time *;string;Конец периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 23:59:59), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 23:59:59 +0400). page;number;Номер страницы (положительное целое число). status_id;array / number;ID статуса (данные по сотрудникам, которые использовали определённый статус в выбранный период). role_id;array / number;ID роли сотрудников (данные по сотрудникам, для которых задана определённая роль). staff_access;string;Уровень доступа сотрудников (возможные варианты: full, by_groups,limited, view_only). group_id;array / number;ID группы (данные по сотрудникам с доступом к определённой группе). staff_id;array / number;ID сотрудника (данные по конкретному сотруднику).

Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET "https://[domain].omnidesk.ru/api/stats_staff_statuses.json?from_time=01.09.2023&to_time=01.10.2023&staff_id=193&staff_access=full

Оценки качества работы

GET  |  https://[domain].omnidesk.ru/api/stats_satisfaction.json

Получение списка оценок и комментариев к ним.

Период

1) Если в аккаунте администратора вы обычно смотрите статистику за стандартные периоды, через API есть смысл делать то же самое, используя параметр period. В этом случае не нужно каждый раз определять подходящий timestamp и бескопоиться о том, что данные могут не совпасть с теми, которые администратор видит в своём аккаунте.

2) При получении данных за кастомный период с помощью параметров from_time и to_time минимальный период, который можно задать, составляет 1 час, а максимальный — 3 месяца. В ответ на запрос, в котором задан слишком маленький или слишком большой период, возвращается ошибка.

Кеширование

Обращений, сотрудников и оценок, которые нужно по ним получить, может быть очень много. Поэтому каждый запрос в адрес этого метода не приводит к тому, что Омнидеск заново пересчитывает все данные. В зависимости от заданного периода используется кеш, который хранится определённое время:

last_24_hours — кеш на 5 минут;
last_7_days — кеш на час;
last_14_days — кеш на час;
last_30_days — кеш на день;
today — кеш 5 минут;
yesterday — кеш на день;
this_week — кеш на день;
last_week — кеш на неделю;
this_month — кеш на день;
last_month — кеш на месяц;
month_2 (если сейчас 11.2023, будет 09.2023) — кеш на месяц;
month_3 (если сейчас 11.2023, будет 08.2023) — кеш на месяц;
month_4 (если сейчас 11.2023, будет 07.2023) — кеш на месяц;
month_5 (если сейчас 11.2023, будет 06.2023) — кеш на месяц;
month_6 (если сейчас 11.2023, будет 05.2023) — кеш на месяц;
3_previous_months (три предыдущих, исключая текущий) — кеш на месяц;
6_previous_months (шесть предыдущих, исключая текущий) — кеш на месяц;
this_year — кеш на день;
last_year — кеш на год;
кастомный период от часа до одного дня — кеш на час;
кастомный период от одного дня — кеш на день.

К примеру, если вы хотите получать актуальные данные за сегодня, чтобы отображать график в админке вашего сервиса, можно каждые 5-10 минут выполнять один запрос в адрес этого метода с параметром period=today. Выполнять их чаще нет смысла, так как вы будете получать закешированные данные.

Параметры

period *;string;Выбор одного из стандартных периодов для получения статистических данных. ;;Если используется этот параметр, то параметры «from_time» и «to_time» передавать не нужно, так как они предназначены для указания кастомного периода. ;;Возможные варианты: last_24_hours, last_7_days, last_14_days, last_30_days, today, yesterday, this_week, last_week, this_month, last_month, month_2 (если сейчас 11.2023, будет 09.2023), month_3 (если сейчас 11.2023, будет 08.2023), month_4 (если сейчас 11.2023, будет 07.2023), month_5 (если сейчас 11.2023, будет 06.2023), month_6 (если сейчас 11.2023, будет 05.2023), 3_previous_months (три предыдущих, исключая текущий), 6_previous_months (шесть предыдущих, исключая текущий), this_year, last_year. ;;При расчёте данных используется часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». from_time *;string;Начало периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 00:00:00), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 00:00:00 +0400). to_time *;string;Конец периода для отображения статистики (строковое значение или timestamp). Обязателен, если не передаётся параметр period. ;;Если вы передаёте строковое значение без часового пояса (2021-06-01 23:59:59), мы ориентируемся на часовой пояс, выставленный в настройках аккаунта администратора: раздел «Настройки» → подраздел «Общие настройки» → поле «Часовой пояс по умолчанию». ;;Если хотите получить данные с учётом конкретного часового пояса, передайте его в строковом значении (2021-06-01 23:59:59 +0400). page;number;Номер страницы (положительное целое число). limit;number;Лимит оценок на странице (целое число от 1 до 100). sort;string;▸ added_at_desc — по времени выставления оценки (от новых к старым). ;;▸ added_at_asc — по времени выставления оценки (от старых к новым). rating_id;array / number;ID конкретной оценки. rating;array / string;Оценка обращения или ответа (возможные варианты: low, middle, high). rating_comment;boolean;Оценки с комментариями пользователей или без (возможные варианты: true, false). rated_staff_id;array / number;ID сотрудника (выборка всех оценок, полученных конкретным сотрудником, который был ответственным на момент выставления оценки, или выборка оценок конкретных ответов сотрудника). rated_assignee_role_id;array / number;ID роли ответственных сотрудников (выборка оценок по обращениям, в которых сотрудники с указанной ролью были ответственными на момент выставления оценки). participant_id;array / number;ID сотрудника (выборка оценок по обращениям, в которых указанный сотрудник является участником). participant_role_id ;array / number;ID роли сотрудников, которые являются участниками (выборка оценок по обращениям, в которых сотрудники с указанной ролью являются участниками). user_id;array / number;ID пользователя (выборка всех оценок, выставленных конкретным пользователем). user_email;array / string;Поиск оценок, выставленных пользователем с указанным email-адресом (не менее 4 символов). user_phone;array / string;Поиск оценок, выставленных пользователем с указанным номером телефона (не менее 4 символов). initiator;string;Инициатор обращения (возможные варианты: user, agent). company_id;array / number;ID компании (выборка оценок по обращениям от пользователей конкретной компании). group_id;array / number;ID группы (выборка всех оценок в обращениях указанной группы) channel;array / string;Канал обращения. ;;Возможные варианты: email, web, call, live_chat (онлайн-чат), facebook, fb_chat, vkontakte, vk_chat, twitter, instagram_posts, instagram_chat, ok_chat, telegram, skype, slack, viber, line, zalo, wa_chat (WhatsApp), youscan, avito, idea, cch123 (кастомный канал), sync (все синхронные каналы), async (все асинхронные каналы), social (соцсети), messengers (мессенджеры). status;array / string;Выборка оценок по обращениям с определённым статусом (возможные варианты: open, waiting, closed). priority;array / string;Выборка оценок по обращениям с определённым приоритетом (возможные варианты: low, normal, high, critical). labels;array;Выборка оценок по обращениям с определёнными метками. custom_fields;array;Выборка оценок по обращениям с определёнными данным в дополнительных полях. Фильтровать можно как по полям обращения, так и по полям пользователя. ;;Для фильтрацию по кастомному полю обязательно нужно указать его ID и значение. В зависимости от типа поля, по которому выполняется фильтрация обращений, поиск осуществляется по-разному: ;;▸ «текстовое поле» или «текстовая область» — производится поиск включения передаваемой строки (custom_fields[cf_7604]=text); ;;▸ «чекбокс» — производится поиск по наличию/отсутствию флага в зависимости от передаваемого значения (custom_fields[cf_7605]=0 или custom_fields[cf_7605]=1); ;;▸ «список» — производится поиск по ключу, равному передаваемому значению (custom_fields[cf_7606]=1, custom_fields[cf_7606]=3 и т. д.); ;;▸ «дата» — производится поиск по ключу, равному передаваемому значению (custom_fields[cf_7607]=2023-06-01 или custom_fields[cf_7607]=1685563200).

Ответ

{
    "0": {
        "rating_id": 79,
        "rating": "3",
        "rating_comment": "cool123",
        "rated_staff_id": 193, // передаётся id сотрудника, если оценка выставлена конкретному ответу,        
                               // а не всему обращению
        "case_id": 47232,
        "case_number": "882-935664",
        "user_id": 222760,
        "staff_id": 193,
        "group_id": 318,
        "created_at": "Thu, 16 Jul 2020 15:00:35 +0300",
        "updated_at": "Thu, 16 Jul 2020 15:00:35 +0300"
    },
    "1": {
        "rating_id": 78,
        "rating": "2",
        "rating_comment": "",
        "rated_staff_id": 0, // передаётся «0», если оценка выставлена всему обращению
        "case_id": 47223,
        "case_number": "898-213499",
        "user_id": 213381,
        "staff_id": 193, // сотрудник, который был ответственным на момент оценки
        "group_id": 746,
        "created_at": "Thu, 16 Jul 2020 14:49:38 +0300",
        "updated_at": "Thu, 16 Jul 2020 14:54:50 +0300"
    },
    "total_count": 8
}

Пример кода

curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -g "http://[domain].omnidesk.ru/api/stats_satisfaction.json?from_time=2021-01-01&to_time=2021-31-01&user_id=213450&channel=sync&sort=added_at_asc"