Свои поля
Свои поля — справочник полей компании, которые хранятся в карточке контакта и в карточке диалога (город, номер заказа, срок, причина обращения). Этот раздел описывает сам справочник и запись значений; значения приходят в ответах контактов и диалогов в объекте `custom_fields`.
Типы полей
Тип (type) задаётся при создании и потом не меняется. Значение в запросах и ответах (custom_fields) выглядит так:
| Тип | Значение |
|---|---|
string | Строка до 1000 символов. |
textarea | Многострочный текст до 10 000 символов. В списке контактов обрезается до 500 символов (см. custom_fields_truncated в группе contacts). |
number | Число (не более 14 знаков до запятой и 6 после); можно передать числом или строкой, в ответе приходит каноничная запись без хвостовых нулей. settings.decimals (0–6) — только подсказка для отображения. |
date | Строка YYYY-MM-DD. |
select | Ключ одного варианта из options[].key. Вариант из архива выбрать нельзя (archived_option). |
multiselect | Массив ключей вариантов, не больше 50, без повторов. |
checkbox | true или false. |
url | Адрес http:// или https:// до 1000 символов. |
phone | Телефон; в ответе хранится в международном формате E.164. Национальный номер читается по стране компании. |
email | Адрес email до 254 символов. |
Ключ поля
key — латиница в нижнем регистре, цифры и _, начинается с буквы, от 2 до 64 символов. Если не передать, сервер сделает ключ из названия. Ключ уникален среди полей одного типа сущности (контакт, диалог или организация) в компании, включая архивные, и после создания не меняется: на него ссылаются сценарии, сегменты и API. Для вариантов options[].key тоже можно не передавать, ключ создаётся сам.
Права
- Чтение справочника (
GET /custom-fields):contact.viewдляentity_type=contactи дляorganization,conversation.viewдляconversation. Архивные поля (include_archived=1) видит только обладательcustom_field.manage. - Создание, правка, порядок, архив, возврат из архива,
usages:custom_field.manage(администратор и менеджер). - Удаление навсегда (
DELETE):custom_field.delete(только администратор). - Запись значений контакта (
PUT /contacts/{contact}/custom-fields):custom_field_value.updateилиcontact.update; значений диалога:conversation.update; значений организации (PUT /organizations/{organization}/custom-fields):organization.view,organization.updateиcustom_field_value.updateодновременно. Агент без праваcontact.updateтоже может заполнять поля контакта. - Без права ответ —
403для любого id; чужое поле или чужая карточка —404. Токены встроенных виджетов (embed) могут читать справочник и записывать значения, но не менять сам справочник.
Лимиты
- Не более 100 активных полей на компанию отдельно для контактов, для диалогов и для организаций; превышение —
422сcustom_field_limit_reached(то же при возврате из архива). - Не более 200 вариантов у поля
select/multiselect; название и название варианта до 100 символов, описание до 500. - Суммарный размер всех значений одной карточки — не более 32 768 байт, иначе
422сcustom_fields_total_too_large. - Скорость: чтение справочника 60 запросов в минуту, запись справочника 20 в минуту на пользователя; запись значений 120 в минуту на пользователя (у API-токена свой отдельный счётчик). Превышение —
429. - Запись значений недоступна компаниям не типа «бизнес» (например, Kids).
Ошибки
Ошибки валидации приходят как 422 вида {"data": {"message", "errors": {поле: [код]}}}, где код — машинное имя. Справочник: label_required, label_too_long, description_too_long, invalid_key, key_taken, too_many_options, options_required, options_not_allowed, option_label_required, option_label_too_long, invalid_option_key, duplicate_option_label, duplicate_option_key, invalid_decimals, immutable (попытка сменить type, key или entity_type; повторная отправка прежнего значения допустима), ids_mismatch (порядок), custom_field_limit_reached. Значения (путь custom_fields.<key>): unknown_field (нет такого поля или оно в архиве), invalid_type, invalid_format, too_long, too_many_values, unknown_option, archived_option; на весь объект — custom_fields_total_too_large. Повторная отправка уже сохранённого значения ошибкой не считается, даже если вариант потом ушёл в архив.
Архив и удаление
Поле сначала уходит в архив: оно пропадает из ответов, фильтров и выбора, значения у контактов сохраняются, поле можно вернуть (restore). Если поле используется в сценариях, сегментах, ИИ-сотрудниках или рассылках, архивация без confirm: true отвечает 409 с message: "custom_field_in_use" и списком usages; с confirm: true поле архивируется, а перечисленные места перестают его учитывать. Удалить навсегда можно только поле из архива, которое нигде не используется: иначе 409 (custom_field_not_archived или custom_field_in_use). Удаление ставится в очередь (202, custom_field_delete_queued) и стирает значения у всех карточек; отменить нельзя. Архивация, возврат и удаление пишутся в журнал аудита. GET /custom-fields/{id}/usages возвращает {automations, segments, ai_agents, broadcasts}: у сценария {id, name, version_id}, у сегмента и ИИ-сотрудника {id, name}, у рассылки {id, name, status}.
Запись значений
Тело PUT .../custom-fields — только {"custom_fields": {"<key>": значение}}, от 1 до 100 ключей. Запись частичная: переданные ключи устанавливаются, null (или пустая строка, пустой массив) очищает значение, непереданные остаются как были. Любая ошибка отменяет всю запись целиком. Колонки контакта и диалога (status, first_name и т.д.) в этом теле игнорируются. Те же значения можно передать в custom_fields при POST /contacts, PATCH /contacts/{id} и PATCH /conversations/{id}. Источник записи (source: manual, api, automation, ai, import, merge, mcp) сервер определяет сам: запись из кабинета и мобильного приложения — manual, по API-токену — api.
Поля организаций
С 2026-11-17 справочник ведётся и для CRM-организаций: entity_type=organization в GET/POST /custom-fields и PUT /custom-fields/order. Значения приходят в custom_fields организации (список, карточка, вебхуки organization.*), фильтруются и сортируются в GET /organizations так же, как у контактов, и пишутся через PUT /organizations/{organization}/custom-fields. Сценарии, сегменты, ИИ-сотрудники, голосовые агенты и рассылки пока не используют поля организаций, поэтому usages такого поля всегда пустой.
События
Изменения справочника приходят вебхуками группы «Свои поля»: custom_field.created, custom_field.updated (со списком changes), custom_field.archived, custom_field.restored и custom_field.deleted (после того как поле действительно удалено). Смена порядка полей событий не даёт. Изменение значений в карточках приходит в contact.updated, conversation.updated и organization.updated.
Эндпоинты
| Метод | Путь | Описание |
|---|---|---|
| GET | /v1/custom-fieldsСправочник полей (query: entity_type = contact|conversation|organization — обязателен; include_archived = 1 — вместе с архивными, нужно право custom_field.manage). Ответ: data.items. | Справочник полей (query: entity_type = contact|conversation|organization — обязателен; include_archived = 1 — вместе с архивными, нужно право custom_field.manage). Ответ: data.items. |
| POST | /v1/custom-fieldsСоздать поле (body: entity_type, type, label, key?, description?, options[]?, settings?, is_ai_readable?) — 201, data.custom_field. Поле добавляется в конец списка. | Создать поле (body: entity_type, type, label, key?, description?, options[]?, settings?, is_ai_readable?) — 201, data.custom_field. Поле добавляется в конец списка. |
| PATCH | /v1/custom-fields/{customField}Изменить поле (label, description, options[], settings, is_ai_readable, position). type, key и entity_type не меняются (422 immutable). Варианты передаются целиком: отсутствующий в списке вариант уходит в архив, а не удаляется. | Изменить поле (label, description, options[], settings, is_ai_readable, position). type, key и entity_type не меняются (422 immutable). Варианты передаются целиком: отсутствующий в списке вариант уходит в архив, а не удаляется. |
| PUT | /v1/custom-fields/orderЗадать порядок полей (body: entity_type, ids[] — ровно все активные поля этого типа сущности, иначе 422 ids_mismatch). Ответ: data.items. | Задать порядок полей (body: entity_type, ids[] — ровно все активные поля этого типа сущности, иначе 422 ids_mismatch). Ответ: data.items. |
| POST | /v1/custom-fields/{customField}/archiveОтправить поле в архив (body: confirm?). 409 custom_field_in_use со списком usages, если поле используется и confirm не передан. | Отправить поле в архив (body: confirm?). 409 custom_field_in_use со списком usages, если поле используется и confirm не передан. |
| POST | /v1/custom-fields/{customField}/restoreВернуть поле из архива (422 custom_field_limit_reached, если активных полей уже 100). | Вернуть поле из архива (422 custom_field_limit_reached, если активных полей уже 100). |
| GET | /v1/custom-fields/{customField}/usagesГде используется поле: сценарии, сегменты, ИИ-сотрудники, рассылки. | Где используется поле: сценарии, сегменты, ИИ-сотрудники, рассылки. |
| DELETE | /v1/custom-fields/{customField}Удалить поле из архива навсегда вместе со значениями (право custom_field.delete) — 202; 409, если поле не в архиве или ещё используется. | Удалить поле из архива навсегда вместе со значениями (право custom_field.delete) — 202; 409, если поле не в архиве или ещё используется. |
| PUT | /v1/contacts/{contact}/custom-fieldsЗаписать значения своих полей контакта (body: custom_fields). Ответ: data.message и data.contact с актуальными custom_fields. | Записать значения своих полей контакта (body: custom_fields). Ответ: data.message и data.contact с актуальными custom_fields. |
| PUT | /v1/conversations/{conversation}/custom-fieldsЗаписать значения своих полей диалога (body: custom_fields). Ответ: data.message и data.conversation с актуальными custom_fields. | Записать значения своих полей диалога (body: custom_fields). Ответ: data.message и data.conversation с актуальными custom_fields. |
Примеры
Создание поля-списка
Запрос
curl -X POST "https://api.aisar.app/v1/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "contact",
"type": "select",
"label": "Источник",
"options": [{ "label": "Сайт" }, { "label": "Реклама" }, { "label": "Рекомендация" }],
"is_ai_readable": false
}'Ответ
{
"data": {
"custom_field": {
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false },
{ "key": "rekomendatsiia", "label": "Рекомендация", "position": 2, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 3,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T09:30:00.000000Z"
}
}
}Запись значений контакта
Запрос
curl -X PUT "https://api.aisar.app/v1/contacts/45/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"custom_fields": {
"istochnik": "reklama",
"order_number": "A-1042",
"next_call": "2026-11-20",
"old_comment": null
}
}'Ответ
{
"data": {
"message": "Custom fields updated.",
"contact": {
"id": 45,
"display_name": "John Doe",
"custom_fields": {
"istochnik": "reklama",
"order_number": "A-1042",
"next_call": "2026-11-20"
},
"custom_fields_meta": {
"istochnik": {
"updated_at": "2026-11-12T09:35:10+00:00",
"source": "api",
"updated_by": { "id": 7, "name": "Anna Smith" }
}
}
}
}
}Ошибка значения
Запрос
curl -X PUT "https://api.aisar.app/v1/conversations/8123/custom-fields" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "custom_fields": { "deadline": "20.11.2026", "ghost": "x" } }'Ответ
{
"data": {
"message": "The given data was invalid.",
"errors": {
"custom_fields.deadline": ["invalid_format"],
"custom_fields.ghost": ["unknown_field"]
}
}
}Архивация используемого поля
Запрос
curl -X POST "https://api.aisar.app/v1/custom-fields/12/archive" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Ответ
{
"data": {
"message": "custom_field_in_use",
"usages": {
"automations": [{ "id": "a1b2c3", "name": "Welcome", "version_id": "v9" }],
"segments": [{ "id": 4, "name": "From ads" }],
"ai_agents": [],
"voice_agents": [],
"broadcasts": []
}
}
}Справочник полей контакта
Запрос
curl "https://api.aisar.app/v1/custom-fields?entity_type=contact" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"items": [
{
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа",
"description": null,
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 0,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-10T08:00:00.000000Z"
},
{
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 1,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T09:30:00.000000Z"
}
]
}
}Изменение подписи и описания поля
Запрос
curl -X PATCH "https://api.aisar.app/v1/custom-fields/11" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"is_ai_readable": true
}'Ответ
{
"data": {
"custom_field": {
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 0,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-12T10:05:00.000000Z"
}
}
}Новый порядок полей
Запрос
curl -X PUT "https://api.aisar.app/v1/custom-fields/order" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"entity_type": "contact",
"ids": [12, 11]
}'Ответ
{
"data": {
"items": [
{
"id": 12,
"entity_type": "contact",
"key": "istochnik",
"label": "Источник",
"description": null,
"type": "select",
"options": [
{ "key": "sait", "label": "Сайт", "position": 0, "archived": false },
{ "key": "reklama", "label": "Реклама", "position": 1, "archived": false }
],
"settings": {},
"is_ai_readable": false,
"position": 0,
"archived_at": null,
"created_at": "2026-11-12T09:30:00.000000Z",
"updated_at": "2026-11-12T10:10:00.000000Z"
},
{
"id": 11,
"entity_type": "contact",
"key": "order_number",
"label": "Номер заказа в магазине",
"description": "Формат A-0000",
"type": "text",
"options": null,
"settings": {},
"is_ai_readable": true,
"position": 1,
"archived_at": null,
"created_at": "2026-11-10T08:00:00.000000Z",
"updated_at": "2026-11-12T10:10:00.000000Z"
}
]
}
}Возврат поля из архива
Запрос
curl -X POST "https://api.aisar.app/v1/custom-fields/14/restore" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"custom_field": {
"id": 14,
"entity_type": "conversation",
"key": "deadline",
"label": "Срок",
"description": null,
"type": "date",
"options": null,
"settings": {},
"is_ai_readable": false,
"position": 2,
"archived_at": null,
"created_at": "2026-11-01T07:00:00.000000Z",
"updated_at": "2026-11-12T10:20:00.000000Z"
}
}
}Где используется поле
Запрос
curl "https://api.aisar.app/v1/custom-fields/12/usages" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
{
"data": {
"usages": {
"automations": [{ "id": "a1b2c3", "name": "Welcome", "version_id": "v9" }],
"segments": [{ "id": 4, "name": "From ads" }],
"ai_agents": [],
"voice_agents": [],
"broadcasts": [{ "id": 31, "name": "November promo", "status": "scheduled" }]
}
}
}Удаление поля из архива
Запрос
curl -X DELETE "https://api.aisar.app/v1/custom-fields/14" \
-H "Authorization: Bearer YOUR_API_TOKEN"Ответ
// 202 удаление поставлено в очередь / deletion queued
{
"data": {
"message": "custom_field_delete_queued"
}
}
// 409 поле не в архиве / the field is not archived
{
"data": {
"message": "custom_field_not_archived"
}
}