Перейти к содержимому
AISARAISAR
REST API

Свои поля

Свои поля — справочник полей компании, которые хранятся в карточке контакта и в карточке диалога (город, номер заказа, срок, причина обращения). Этот раздел описывает сам справочник и запись значений; значения приходят в ответах контактов и диалогов в объекте `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, без повторов.
checkboxtrue или 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.

POST/v1/custom-fields

Создать поле (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). Варианты передаются целиком: отсутствующий в списке вариант уходит в архив, а не удаляется.

PUT/v1/custom-fields/order

Задать порядок полей (body: entity_type, ids[] — ровно все активные поля этого типа сущности, иначе 422 ids_mismatch). Ответ: data.items.

POST/v1/custom-fields/{customField}/archive

Отправить поле в архив (body: confirm?). 409 custom_field_in_use со списком usages, если поле используется и confirm не передан.

POST/v1/custom-fields/{customField}/restore

Вернуть поле из архива (422 custom_field_limit_reached, если активных полей уже 100).

GET/v1/custom-fields/{customField}/usages

Где используется поле: сценарии, сегменты, ИИ-сотрудники, рассылки.

DELETE/v1/custom-fields/{customField}

Удалить поле из архива навсегда вместе со значениями (право custom_field.delete) — 202; 409, если поле не в архиве или ещё используется.

PUT/v1/contacts/{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.

Примеры

Создание поля-списка

Запрос

bash
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
  }'

Ответ

json
{
  "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"
    }
  }
}

Запись значений контакта

Запрос

bash
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
    }
  }'

Ответ

json
{
  "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" }
        }
      }
    }
  }
}

Ошибка значения

Запрос

bash
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" } }'

Ответ

json
{
  "data": {
    "message": "The given data was invalid.",
    "errors": {
      "custom_fields.deadline": ["invalid_format"],
      "custom_fields.ghost": ["unknown_field"]
    }
  }
}

Архивация используемого поля

Запрос

bash
curl -X POST "https://api.aisar.app/v1/custom-fields/12/archive" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

Ответ

json
{
  "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": []
    }
  }
}

Справочник полей контакта

Запрос

bash
curl "https://api.aisar.app/v1/custom-fields?entity_type=contact" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "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"
      }
    ]
  }
}

Изменение подписи и описания поля

Запрос

bash
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
  }'

Ответ

json
{
  "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"
    }
  }
}

Новый порядок полей

Запрос

bash
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]
  }'

Ответ

json
{
  "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"
      }
    ]
  }
}

Возврат поля из архива

Запрос

bash
curl -X POST "https://api.aisar.app/v1/custom-fields/14/restore" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "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"
    }
  }
}

Где используется поле

Запрос

bash
curl "https://api.aisar.app/v1/custom-fields/12/usages" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
{
  "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" }]
    }
  }
}

Удаление поля из архива

Запрос

bash
curl -X DELETE "https://api.aisar.app/v1/custom-fields/14" \
  -H "Authorization: Bearer YOUR_API_TOKEN"

Ответ

json
// 202 удаление поставлено в очередь / deletion queued
{
  "data": {
    "message": "custom_field_delete_queued"
  }
}
// 409 поле не в архиве / the field is not archived
{
  "data": {
    "message": "custom_field_not_archived"
  }
}