📚
База знаний | Qolio.io
  • Обзор Qolio
  • Видеоинструкции
    • Интеграция с Битрикс24
    • Права доступа и уровни сотрудников
    • Дополнительные отделы
    • Структура компании
    • Страница "Сотрудники"
    • Настройки организации
    • Управление аккаунтом
    • Страница "Формы оценки"
    • Настройка критериев
    • Настройка формы оценки
    • Cтраница "Список коммуникаций"
    • Конфигурации фильтров
    • Фильтры на "Списке коммуникаций"
    • Как оценить звонок?
    • Как оценить текстовую коммуникацию?
    • Быстрая проверка
    • Где найти мою проверку?
    • Статусы контакта
    • Теги
    • Библиотека звонков
    • Как загрузить звонки
    • Распределение нагрузки
    • Как отслеживать прогресс сотрудников
    • Калибровочные сессии
    • Апелляции: настройка
    • Как подать апелляцию
    • Обработка апелляции
    • Страница "Отчеты": Динамика оценок по отделам
    • Страница "Отчеты": Аналитика по апелляциям
    • Страница "Отчеты": Команда
    • Страница "Аналитика"
    • Личный кабинет Оператора
    • Распределение нагрузки: видео-обзор функции
  • Быстрые клавиши
  • Как написать сообщение в поддержку?
  • Последние обновления
    • Возможность менять оператора, ответственного за звонок
    • Улучшения в настройках аналитики и интеграции
    • Перезагрузка плеера во время проверки
    • Дополнительные отделы, больше информации по сделкам из AmoCRM и другие возможности
    • Отображение результатов по дате оценки и другие новые возможности
    • Апелляции на любые типы коммуникаций
    • Отображение аналитики по дате оценки в разделах “Личный кабинет” и “Команда” уже доступно
    • Простая интеграция с HelpDeskEddy
  • Возможности платформы
    • Список коммуникаций
    • Формы оценки
      • Настройка форм оценки
      • Критерии формы оценки
      • Зоны оценки
      • Подсчет результатов по формам оценки
        • Процентное/Простая/Сумма
        • Процентное/Простая/Средний балл
        • Процентное/Взвешенная/Средний балл
        • Числовое/Простая/Сумма
        • Числовое/Простая/Средний балл
        • Числовое/Взвешенная/Средний балл
    • Проверка коммуникаций
      • Как оценить звонок
      • Быстрая проверка
    • Браузерное расширение
    • Теги
    • Библиотека звонков
    • Статусы контакта
    • Апелляции
      • Как подать апелляцию?
      • Как обработать апелляцию
    • Аналитика
      • Как настроить аналитику
      • Как посмотреть аналитику по дате оценки
      • Отчёт "Динамика оценок по отделам"
      • Команда
      • XL-виджеты
        • Результаты проверок по сотрудникам
        • Результаты сотрудников по критериям
        • Результаты проверок по критериям
        • Количество проверок по проверяющим
        • Результаты сотрудников по формам оценки
        • Результаты сотрудников по форме оценки
        • Флаги и комментарии
      • L-виджеты
        • Динамика среднего балла по отделам
        • Динамика балла по группам вопросов формы оценки
        • Динамика балла по вопросам формы оценки
        • Динамика количества проверенных звонков
        • Динамика количества звонков по сотрудникам
        • Динамика средней продолжительности звонка по сотрудникам
        • Динамика количества звонков по отделам
        • Динамика средней продолжительности звонка по отделам
        • Динамика среднего балла по сотрудникам
      • M-виджеты
        • Сравнение среднего балла по сотрудникам
        • Количество флагов и комментариев
        • Сравнение количества флагов по сотрудникам
        • Сравнение среднего балла по отделам
        • Сравнение количества тегов по отделам
        • Сравнение среднего балла по формам оценки
        • Сравнение среднего балла по вопросам в форме оценки
        • Сравнение количества тегов по сотрудникам
        • Сравнение среднего балла в группах формы оценки
        • Сравнение среднего балла вопросов в группах
        • Сравнение количества звонков по отделам
        • Сравнение количества звонков по сотрудникам
        • Сравнение количества проверок супервизоров
        • Сравнение средней продолжительности звонков по сотрудникам
        • Сравнение количества флагов по отделам
        • Сравнение средней продолжительности звонков по отделам
      • S-виджеты
        • Количество звонков
        • Общая продолжительность звонков
        • Процент проверок
        • Средняя продолжительность звонка
        • Средний балл по форме оценки
    • Калибровочные сессии
    • Личный кабинет Оператора
    • Распределение нагрузки: общий обзор функции
      • Распределение нагрузки: как отслеживать процесс проверок
      • Распределение нагрузки: как оценивать коммуникации
    • Настройки пользователей и отделов
      • Как пригласить сотрудников в Qolio
      • Настройки прав доступа и уровней сотрудников
      • Дополнительные отделы
      • Добавление новых сотрудников и смена пароля
      • Как добавить нового сотрудника из вашей системы
      • Настройка уведомлений и статусов
      • Страница "Подключения"
  • Интеграции
    • Битрикс 24
      • Bitrix (Коробочная Версия): Разрешение Доступа
    • AmoCRM
      • Как просмотреть все коммуникации из сделки AmoCRM
      • Если не получается оценить звонок из AmoCRM
      • Авторизация в amoCRM
    • Что делать после установки Qolio в AmoCRM/Битрикс24?
    • Usedesk
    • Binotel
    • Sipuni
    • Zendesk
    • HelpDeskEddy
    • UIS/Comagic
    • Edna
    • MANGO OFFICE
    • Подключение по API
      • Интеграция по API для IP-телефонии и чатов
        • API запрос для добавления звонков
          • API запрос для добавления звонка с транскрибцией
        • API запрос для добавления звонков с хранением данных на S3
        • HTTPS интеграция с текстовыми каналами (через API Qolio)
      • Создание csv файла для добавления пользователей при интеграции по API
      • Создание и управление пользовательскими полями при интеграции по API
      • Синхронизация аккаунтов пользователя в системе Qolio и интегрируемой системы
      • Доступ через API
      • Добавление и настройка пользователей через API
      • Custom Fields API - Настройка пользовательских полей
      • Возможные ошибки API
      • Получение оценок операторов по API
      • Приложение (информация о полях в объектах JSON:API)
    • Установка коробочной версии на одной машине (single-node deployment)
    • Oktell: Общие сведения для подключения
    • Asterisk: Общие сведения о настройке интеграции
  • Вопросы
    • Что делать, если по сотрудникам нет коммуникаций
    • Доступ к Qolio через VPN
    • Если в браузере не проигрывается звонок с http-ссылкой
    • "Установленные настройки недоступны" - что делать?
  • Безопасность
    • Облачная версия
Powered by GitBook
On this page
  • Введение
  • Методы API
  • Пользовательские поля (custom_fields)
  • Работа с зависимыми полями (select)

Was this helpful?

  1. Интеграции
  2. Подключение по API

Custom Fields API - Настройка пользовательских полей

PreviousДобавление и настройка пользователей через APINextВозможные ошибки API

Last updated 1 year ago

Was this helpful?

Введение

В данной статье будет рассказано, как можно создавать и настраивать пользовательские поля через DealApp API. Все методы, описанные ниже требуют авторизацию через пользователя с настроенными правами по обновлению пользователей. О том, как производить авторизацию, можно прочитать в статье

Пользовательские поля (Custom Fields) это дополнительные поля, которые добавляются к звонкам и другим объектам коммуникаций с клиентами (Client Interactions), таким как чаты и тикеты. Эти поля расширяют основную схему таких объектов для реализации дополнительной бизнес логики. По этим полям можно фильтровать список на странице Таблицы Коммуникаций и эти данные можно так же увидеть на странице оценки.

Примеры возможных значений в таких полях:

  1. Проект или контракт по которому совершался звонок

  2. Город из которого пришел звонок

  3. Время последнего закрытия тикета

  4. Кол-во закрытий тикета или дата последнего закрытия

  5. Массив NPS с опросом клиента о качестве. Сценарий такой: диалог в тикете может открываться или закрываться несколько раз, каждое значение оценки записывается и может передаваться нам в виде массива.

  6. Список тематик. При чем тематики могут иметь под-тематики, список которых будет зависеть от тематики

Значения пользовательских полей хранятся в объекте ClientInteraction в виде json поля custom_fields. Данные хранятся как пары ключ-значения, где ключ используется для того, чтобы сопоставить значение с ресурсом Custom Field. Пример получения данных о Custom Field:

{
  "data": {
    "id": "16915806-8327-4899-9e1c-6a59474c877b",
    "type": "phone-calls",
    "attributes": {
      ...
      "custom-fields": {
        "opened_at": "2020-06-21T09:51:13.588Z",
        "reopen_count": 5,
        "sale_stage": "negotiations"
      }
    },
    "relationships": {
      "operator": {...}
    }
  }
}

Методы API

Пользовательские поля (custom_fields)

GET /api/v1/custom_fields

Пример запроса: curl -X GET -H @headers.txt https://api.dev.dealapp.io/api/v1/custom_fields

{
  "data": [
    {
      "id": "0dce0ebb-8b2f-4c1d-a1d0-470658aab301",
      "type": "custom-fields",
      "attributes": {
        "name": "Closed",
        "field-type": "boolean",
        "key": "closed",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "12f19196-7ca6-4f85-b935-bb22c12a706c",
      "type": "custom-fields",
      "attributes": {
        "name": "Список тегов",
        "field-type": "string_array",
        "key": "tags_array",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "19026429-c69f-4c02-992b-703d6b0847a1",
      "type": "custom-fields",
      "attributes": {
        "name": "Список NPS",
        "field-type": "number_array",
        "key": "nps_array",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "4f290222-a594-4d29-a3ee-6707c0f1c919",
      "type": "custom-fields",
      "attributes": {
        "name": "Кол-во перезвонов",
        "field-type": "number",
        "key": "reopen_count",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "7118af32-4e6f-49ff-905e-f4fb1929c7b7",
      "type": "custom-fields",
      "attributes": {
        "name": "Рандомная дата",
        "field-type": "datetime",
        "key": "opened_at",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "9c831219-d8bf-406f-9b65-f46225d8e3f4",
      "type": "custom-fields",
      "attributes": {
        "name": "Подтема",
        "field-type": "string",
        "key": "subtopic",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "a9305929-ada0-4c5f-b824-7628a7aa4e6b",
      "type": "custom-fields",
      "attributes": {
        "name": "Тема",
        "field-type": "string",
        "key": "topic",
        "description": null,
        "options": [],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    },
    {
      "id": "660464e7-9e2b-4047-83a5-b3ef0bcf1444",
      "type": "custom-fields",
      "attributes": {
        "name": "Voronka",
        "field-type": "enum",
        "key": "sales_funnel",
        "description": "Voronka prodazh",
        "options": [
          "first contact",
          "negotiations",
          "done",
          "failed"
        ],
        "settings": {},
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    }
  ],
  "links": {
    "self": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "first": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25",
    "prev": null,
    "next": null,
    "last": "https://api.dev.dealapp.io/api/v1/custom_fields?page%5Bnumber%5D=1&page%5Bsize%5D=25"
  },
  "meta": {
    "page": 1,
    "total-pages": 1,
    "total-count": 8
  }
}

POST /api/v1/custom_fields

Создание пользовательского поля

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

curl -X POST \
     -H @headers.txt \
     --data '{
        "key": "city",
        "name": "Название",
        "field_type": "enum",
        "options": ["Москва", "Санкт-Петербург"]
      }' \
     -H "Content-Type: application/json" \
     https://api.dev.dealapp.io/api/v1/custom_fields

PUT /api/v1/custom_fields

Обновление пользовательского поля, при обновлении реализовано частичное обновление полей объектов (можно указывать только те, которые обновляются). Однако options и select поля нужно определять полностью.

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

curl -X PUT \
     -H @headers.txt \
     --data '{
        "name": "Название Города",
        "options": ["Москва", "Санкт-Петербург", "Воронеж"]
      }' \
     -H "Content-Type: application/json" \
     https://api.dev.dealapp.io/api/v1/custom_fields

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

{
  "data": {
    "id": "f3c1c90c-f184-4c1c-8cca-be55d2d9d0e9",
    "type": "custom-fields",
    "attributes": {
      "name": "Название",
      "field-type": "enum",
      "key": "city",
      "description": null,
      "options": [
        "Москва",
        "Санкт-Петербург"
      ],
      "settings": {},
      "used-for-reviews": true,
      "used-for-filters": true
    },
    "relationships": {
      "depends-on": {
        "data": null
      }
    }
  }
}

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

{
  "data": {
    "id": "f3c1c90c-f184-4c1c-8cca-be55d2d9d0e9",
    "type": "custom-fields",
    "attributes": {
      "name": "Название",
      "field-type": "enum",
      "key": "city",
      "description": null,
      "options": [
        "Москва",
        "Санкт-Петербург"
      ],
      "settings": {},
      "used-for-reviews": true,
      "used-for-filters": true
    },
    "relationships": {
      "depends-on": {
        "data": null
      }
    }
  }
}

Работа с зависимыми полями (select)

Custom Field со значением field_type select позволяют создавать поля с возможностью выбора вариантов, которые зависят от значения других полей с таким же типом. Так же значения поля settings в таких selectCustom Field будут хранить объекты с полями key, text и parent-key. Поле key в этом объекте будет использоваться как id этого варианта ответа, text - для отображения варианта на UI, а parent-key будет задавать значение key в другом select поле, от которого зависит данное поле, при котором этот вариант должен отображаться в данном селекте на UI.

Пример такого объекта:

{
  "data": [
    {
      "id": "8cf921ee-9085-4959-acd0-c64dd4c3cb63",
      "type": "custom-fields",
      "attributes": {
        "name": "Child",
        "field-type": "select",
        "key": "children",
        "description": null,
        "options": [],
        "settings": [
          {
            "key": "child-1-1",
            "text": "Child 1.1",
            "parent-key": "parent-1"
          },
          {
            "key": "child-1-2",
            "text": "Child 1.2",
            "parent-key": "parent-1"
          },
          {
            "key": "child-2-1",
            "text": "Child 2.1",
            "parent-key": "parent-2"
          },
          {
            "key": "child-2-2",
            "text": "Child 2.2",
            "parent-key": "parent-2"
          }
        ],
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": {
            "id": "ac0f998e-d14f-479d-8498-d1c6f71e8282",
            "type": "custom-fields"
          }
        }
      }
    },
    {
      "id": "ac0f998e-d14f-479d-8498-d1c6f71e8282",
      "type": "custom-fields",
      "attributes": {
        "name": "Parent",
        "field-type": "select",
        "key": "parent",
        "description": null,
        "options": [],
        "settings": [
          {
            "key": "parent-1",
            "text": "Parent 1"
          },
          {
            "key": "parent-2",
            "text": "Parent 2"
          }
        ],
        "used-for-reviews": true,
        "used-for-filters": true
      },
      "relationships": {
        "depends-on": {
          "data": null
        }
      }
    }
  ]
}

Такая конфигурация задает 2 зависимых поля: Parent и Child. При выборе значения Parent 1 в поле Child будет возможность выбрать только Child 1.1 и Child 1.1. В целом зависимость значений будет выглядеть следующим образом.

├── Parent 1
|       ├── Child 1.1
|       └── Child 1.2
└── Parent 2
        ├── Child 2.1
        └── Child 2.2

select Custom Field работают точно так же как и остальные со следующими изменениями:

  • добавлено поле depends_on, которое обозначает поле от которого зависит это поле

  • добавлено поле settings, в котором храниться массив с настройками возможных значения поля select

В settings хранится массив объектов, в каждом объекте есть следующие поля:

  • key - ключ по которому будет проходить поиск

  • text - текст, который соответствует значение key

  • parent_key - значение ключа key в select поле c depends_on, по которому должно отображаться это поле

  • Пример скрипта, который создает зависимые поля через bash с помощью curl

Возвращает список объектов пользовательских полей () для вашей организации

Добавление и настройка пользователей через API
custom-fields