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_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"

Лучшие в команде по сотрудникам *


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

* Данные из старой версии статистики. Метод будет отключен 01.02.2024

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

Средние скорость первого ответа и скорость закрытия выводятся в секундах.

Параметры

Ответ


{
  "staff" : {
    "staff_id" : 100,
    "staff_name" : "Viktor Persov",
    "new_assigned_cases": 293,
    "cases_with_first_reply" : 251,
    "first_reply_speed" : 28,
    "total_amount_of_replies": 457,
    "total_amount_of_notes": 56,
    "closed_cases" : 212,
    "closing_speed" : 445,
    "average_rating" : 84%
  },
  "staff" : {
    "staff_id" : 102,
    "staff_name" : "Stas Pokrasin",
    "new_assigned_cases" : 65,
    "cases_with_first_reply" : 61,
    "first_reply_speed" : 43,
    "total_amount_of_replies" : 137,
    "total_amount_of_notes": 16,
    "closed_cases" : 49,
    "closing_speed" : 409,
    "average_rating" : 79%
  },
}

Пример кода


curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET "https://[domain].omnidesk.ru/api/stats_lb_staff.json?from_time=01+Jan+2015+00%3A00%3A00+%2B0300&to_time=05+Dec+2015+00%3A00%3A00+%2B0300"

Лучшие в команде по группам *


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

* Данные из старой версии статистики. Метод будет отключен 01.02.2024

Лучшие в команде по группам.

Средние скорость первого ответа и скорость закрытия выводятся в секундах.

Параметры

Ответ


{
  "group" : {
    "group_id" : 21,
    "group_name" : "General questions",
    "new_assigned_cases": 103,
    "total_amount_of_notes": 25,
    "cases_with_first_reply" : 86,
    "first_reply_speed" : 36,
    "total_amount_of_replies" : 194,
    "closed_cases" : 57,
    "closing_speed" : 458,
    "average_rating" : 82%
  },
  "staff" : {
    "group_id" : 22,
    "group_name" : "Billing questions",
    "new_assigned_cases": 45,
    "total_amount_of_notes": 12,
    "cases_with_first_reply" : 38,
    "first_reply_speed" : 42,
    "total_amount_of_replies" : 91,
    "closed_cases" : 35,
    "closing_speed" : 607,
    "average_rating" : 89%
  },
}

Пример кода


curl -u [staff_email]:[api_key] -H "Content-Type: application/json" -X GET "https://[domain].omnidesk.ru/api/stats_lb_groups.json?from_time=01+Jan+2015+00%3A00%3A00+%2B0300&to_time=05+Dec+2015+00%3A00%3A00+%2B0300"