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

Введение

В данной статье мы расскажем, как можно получить информацию об оценках пользователя за определенный промежуток времени: оператор, месяц, оценка, количество оценённых звонков

Для начала, вам нужно понимать, как работает авторизация и какие базовые принципы используются в 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": "alex@dealapp.io",
        "name": "Alex@dealapp.io ",
        "first-name": null,
        "last-name": "Alex@dealapp.io",
        "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 средняя оценка

PreviousВозможные ошибки APINextПриложение (информация о полях в объектах JSON:API)

Last updated