Получение оценок операторов по API

Введение

В данной статье мы расскажем, как можно получить информацию об оценках пользователя за определенный промежуток времени: оператор, месяц, оценка, количество оценённых звонков
Для начала, вам нужно понимать, как работает авторизация и какие базовые принципы используются в API. Это можно посмотреть в этой статье:
Для получения всех необходимых данных вам придется делать 2 типа запросов:
  • Получение ресурсов - например, список пользователей, для того, чтобы сопоставить их ID с результатами в аналитике, список форм оценок и так далее
  • Получение необходимых данных из аналитики

Получение ресурсов

Для получение списка данных, вам понадобится работать со страницами списков. Вот как это работает

Пагинация

Все ресурсы в системе (кроме отельных виджетов аналитики) отображаются использую страницы данных. Для управления переходами по страницам используются следующие параметры GET запроса:
  • page[number] - номер страницы.
  • page[size] - размер страницы, по умолчанию - 25, максимальное значение 100 (для каких-то ресурсов 500).
При ответе данных со списком ресурсов к ответу добавляется поле meta, в котором хранятся данные о пагинации, которая используется при выполнении данного запроса:
"meta": {
"page": 1,
"total-pages": 10,
"total-count": 97
}
Пример запроса в пагинацией: получение 2ой страницы оценок с размером 10 записей на страницу:
GET /api/v1/reviews?page[number]=2&page[size]=10
Ответ запроса с пагинацией:
{
"data": [
{
"id": "544b74c2-5095-441a-96ab-2d8ac1a574f0",
"type": "reviews",
// ...
}
// тело ответа, основные данные ресурсов
],
"meta": {
"page": 1,
"total-pages": 10,
"total-count": 97
}
}

Список пользователей

Все пользователи, которые используют Qolio имеют свой ID внутри системы. У каждого оператора есть роль, которая связана с правами.Для получения списка пользователей, которые общаются с клиентами и являются операторами в системе, можно использовать фильтр with_role_permissions со значением can_perform_client_interactions.По умолчанию, система возвращает только активных пользователей. Если вы хотите получить информацию обо всех пользователях, в том числе и неактивными, вы можете применить фильтр with_inactive со значением true.Пример запроса всех операторов в системе:GET /api/v1/users?filters[with_role_permissions]=can_perform_client_interactions&filters[with_inactive]=true​Пример ответа:
{
"data": [
{
"id": "8583a9f9-ed5f-431c-896c-c47e8d2bda3e",
"type": "users",
"attributes": {
"email": "[email protected]",
"name": "[email protected] ",
"first-name": null,
"last-name": "[email protected]",
"phone-number": null,
"accepted-invitation": false,
"integration-uid": "6017104",
"avatar-url": null,
"active": true,
"collisions-on-create": {},
"invitation-sent": false,
"last-active-at": null,
"prefered-locale": "ru"
},
"relationships": {
"role": {
"data": {
"id": "239f9770-373e-434e-928c-1b34189e7c1e",
"type": "roles"
}
},
"unit": {
"data": {
"id": "e64c5668-eb91-4582-b121-fe14a0e29791",
"type": "units"
}
},
"level": {
"data": null
},
"origin-integration": {
"data": {
"id": "9e0323e9-17a2-4780-89e9-1fd7be6941e4",
"type": "integrations"
}
}
}
}
]
}
Возможные фильтры:
Фильтры для ресурса users
Фильтр
Значение
with_inactive
вернуть всех пользователей
active
true / false
units_ids
ID отделов внутри Qolio через запятую
roles_ids
ID ролей внутри Qolio через запятую
levels_ids
ID уровней сотрудников внутри Qolio через запятую
integration_uids
ID во внешней системе (operator_id при передаче данных по API)
invitation_status
no_invitation_sent / invitation_sent / invitation_accepted / user_blocked
with_role_permissions

Список форм оценок (чек-листов)

Список форм оценок необходим для получения ID чек-листов, по которым будет возвращаться аналитика. Endpoint /api/v2/checklist/definitions возвращает данные сразу со вложенными ресурсами - списком критериев (questions) и группами. Критерии соединены с группами с помощью ресурса question-to-group-bindings
Пример запроса:
GET /api/v2/checklist/definitions
Пример ответа:
{
"data": [
{
"id": "544b74c2-5095-441a-96ab-2d8ac1a574f0",
"type": "reviews",
"attributes": {
"created-at": "2021-07-28T13:39:06.624Z"
},
"relationships": {
"reviewer": {
"data": {
"id": "be067ee8-07e6-434a-8c4a-2f397548b894",
"type": "users"
}
},
"client": {
"data": null
},
"checklist": {
"data": {
"id": "b699e10c-8194-4055-a691-2ecdb8ddf1a0",
"type": "checklists"
}
},
"operator": {
"data": {
"id": "c0e8ef30-7238-4855-ad3e-bba651d64b91",
"type": "users"
}
},
"phone-call": {
"data": null
},
"text-communication": {
"data": null
},
"client-interaction": {
"data": {
"id": "d5f27009-3e1d-4eaa-a3eb-69b6237cf49f",
"type": "client-interactions"
}
},
"tasks": {
"data": []
},
"comments": {
"data": []
}
}
}
],
"included": [
{
"id": "82ff2d3c-4bbe-4983-9675-c2d05f259808",
"type": "checklists",
"attributes": {
"metadata": {},
"score": 0,
"max-score": 100,
"comment": "",
"checklist-definition-data": {
"name": "unary",
"is-weighted": false,
"is-groupable": false,
"question-groups": [
{
"id": "a1e424a1-f942-4e8a-be3e-c813ce9b1dc7",
"name": "Критерии без группы"
}
],
"rating-calculation": "sum"
},
"deleted-at": null
},
"relationships": {
"review": {
"data": {
"id": "1066f843-b5db-4409-90aa-18c21b82f7d2",
"type": "reviews"
}
},
"checklist-definition": {
"data": {
"id": "3f62891e-0550-481b-8a20-edc3fefb6a6c",
"type": "checklist-definitions"
}
},
"answers": {
"data": [
{
"id": "84557aa7-ba5c-4dd7-82b8-8149b48b9126",
"type": "checklist-answers"
}
]
}
}
}
]
}

Список оценок

При необходимости можно получить список всех оценок оператора с оценками. Сейчас это можно сделать через endpoint /api/v1/reviews. Чтобы получить вложенный ресурс со значением оценки, вы можете использовать include параметр для ресурса checklist, в котором будет хранится значение оценки в полях score.
В итоге запрос, который будет вытаскивать оценки за март со значениями оценок будет выглядеть следующим образом:
GET /api/v1/reviews?include=checklist&filters[review_time_from]=2021-03-01T00:00:00&filters[review_time_to]=2021-03-31T23:59:59
Пример ответа:
{
"data": [
{
"id": "544b74c2-5095-441a-96ab-2d8ac1a574f0",
"type": "reviews",
"attributes": {
"created-at": "2021-07-28T13:39:06.624Z"
},
"relationships": {
"reviewer": {
"data": {
"id": "be067ee8-07e6-434a-8c4a-2f397548b894",
"type": "users"
}
},
"client": {
"data": null
},
"checklist": {
"data": {
"id": "b699e10c-8194-4055-a691-2ecdb8ddf1a0",
"type": "checklists"
}
},
"operator": {
"data": {
"id": "c0e8ef30-7238-4855-ad3e-bba651d64b91",
"type": "users"
}
},
"phone-call": {
"data": null
},
"text-communication": {
"data": null
},
"client-interaction": {
"data": {
"id": "d5f27009-3e1d-4eaa-a3eb-69b6237cf49f",
"type": "client-interactions"
}
},
"tasks": {
"data": []
},
"comments": {
"data": []
}
}
}
],
"included": [
{
"id": "82ff2d3c-4bbe-4983-9675-c2d05f259808",
"type": "checklists",
"attributes": {
"metadata": {},
"score": 0,
"max-score": 100,
"comment": "",
"checklist-definition-data": {
"name": "unary",
"is-weighted": false,
"is-groupable": false,
"question-groups": [
{
"id": "a1e424a1-f942-4e8a-be3e-c813ce9b1dc7",
"name": "Критерии без группы"
}
],
"rating-calculation": "sum"
},
"deleted-at": null
},
"relationships": {
"review": {
"data": {
"id": "1066f843-b5db-4409-90aa-18c21b82f7d2",
"type": "reviews"
}
},
"checklist-definition": {
"data": {
"id": "3f62891e-0550-481b-8a20-edc3fefb6a6c",
"type": "checklist-definitions"
}
},
"answers": {
"data": [
{
"id": "84557aa7-ba5c-4dd7-82b8-8149b48b9126",
"type": "checklist-answers"
}
]
}
}
}
]
}
Список фильтров для ресурса reviews
Название
Значение
review_symbolic_time_range
Название периода времени создания оценки. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.
review_time_from
С какого времени создавалась оценка
review_time_to
По какое время создавалась оценка
client_interaction_symbolic_time_range
Название периода времени создания коммуникации, по которой совершалась оценка. Возможные значения: today yesterday / last_seven_days / last_thirty_days / this_week / previous_week / this_month и др.
client_interaction_time_from
С какого времени создания коммуникации, по которой совершалась оценка
client_interaction_time_to
По какое время создания коммуникации, по которой совершалась оценка
checklist_definition_color_zones
В какую цветовую зону попала оценка
client_interaction_direction
Направление коммуникации (incoming / outcoming)
communication_type
тип коммуникации (phone_call / video / chat / email / ticket / other)
has_tasks
У оценки есть теги
has_comments
У оценки есть комментарии
units_ids
Отдел оценки (список через запятую)
operators_ids
Список ID операторов через запятую
reviewers_ids
Список ID пользователей, которые создали оценку
checklist_definitions_ids
Список ID форм оценок через запятую
comments_rating_flags
С флагами комментария

Получение аналитики

В Qolio есть возможность получать результаты аналитики по API при этом используется endpoint /api/v1/analytics/widgets и в параметрах передаются данные о необходимой аналитике и фильтрам. Фильтры используются те же что и для ресурса reviews. Чтобы передать название аналитики, которое нужно вернуть используется параметр widget_names, в него передаются названия виджетов через запятую. Возможные варианты названий виджетов будут рассмотрены далее.

Средняя оценка по формам оценки (чек-листам)

Название виджета - checklist_definition_average_score_by_operators
В этом виджете мы рекомендуем всегда использовать фильтр checklist_definitions_ids так как у разных форм оценок могут быть шкалы с разными значениями и средняя оценка по ним будет неинформативной
Список фильтров для виджета "Средняя оценка по сотруднику"
client_interaction_time_to
Название
client_interaction_time_from
client_interaction_symbolic_time_range
client_interaction_direction
units_ids
operators_ids
checklist_definitions_ids
Пример запроса:
GET /api/v1/analytics/widgets?widget_names=checklist_definition_average_score_by_operators&filters[client_interaction_symbolic_time_range]=this_month
Пример ответа:
{
"checklist_definition_average_score_by_operators": [
{
"value": 0.763636363636364,
"name": "Gebo kiersten",
"id": "09a1866a-77be-4a61-adae-c46d2102794d"
},
{
"value": 15.589002267573695,
"name": "Hibbits félicie",
"id": "0b76341c-ccb5-4fde-86c7-2b19c30f53d7"
}
]
}
В этих данных
  • id ID пользователя внутри qolio
  • name имя пользователя
  • value средняя оценка