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

Введение

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

Добавление и настройка пользователей через 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

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