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

Введение

В данной статье будет рассказано, как можно создавать и настраивать пользовательские поля через DealApp API. Все методы, описанные ниже требуют авторизацию через пользователя с настроенными правами по обновлению пользователей. О том, как производить авторизацию, можно прочитать в статье
Пользовательские поля (Custom Fields) это дополнительные поля, которые добавляются к звонкам и другим объектам коммуникаций с клиентами (Client Interactions), таким как чаты и тикеты. Эти поля расширяют основную схему таких объектов для реализации дополнительной бизнес логики. По этим полям можно фильтровать список на странице Таблицы Коммуникаций и эти данные можно так же увидеть на странице оценки.
Примеры возможных значений в таких полях:
  1. 1.
    Проект или контракт по которому совершался звонок
  2. 2.
    Город из которого пришел звонок
  3. 3.
    Время последнего закрытия тикета
  4. 4.
    Кол-во закрытий тикета или дата последнего закрытия
  5. 5.
    Массив NPS с опросом клиента о качестве. Сценарий такой: диалог в тикете может открываться или закрываться несколько раз, каждое значение оценки записывается и может передаваться нам в виде массива.
  6. 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

Возвращает список объектов пользовательских полей (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