Clomni

Scope и endpoint: контакты, метки, пользовательские поля, готовые ответы

Обновлено: 11 ноября 2026 · 13 мин чтения

Scope для контактов, их меток, заметок и компаний, каталога меток, пользовательских полей и готовых ответов. Записывайте ID из своей системы в поле контакта identifier: оно уникально в пределах workspace.

Шаги

  1. 1

    Как читать эту статью

    • Пути пишутся после https://api.clomni.ai/v1: GET /v1/agents означает https://api.clomni.ai/v1/agents. В пути нет ID workspace, потому что токен привязан к одному workspace.
    • В каждом запросе есть заголовок Authorization: Bearer clomni_pat_xxx. Как получить токен: Токены и аутентификация в Developer API.
    • Риск: низкий (нет персональных данных), средний (читает данные клиентов или меняет внутренние данные), высокий (отправляет клиентам, удаляет, массово выгружает, меняет рабочие настройки).
    • Каждый scope проходит review, в public app тоже. Подробнее: Review: проверка scope и причины отказа.
    • «Дополнительно даёт»: write и manage дают и read того же ресурса. send, delete, publish, assign, run ничего не дают.
    • Если endpoint открывается несколькими scope, достаточно одного. Без scope API отвечает 403 insufficient_scope, в ответе есть required_scopes.
    • Каждый POST принимает заголовок Idempotency-Key: повторный запрос не выполняется дважды.
  2. 2

    Читать контакты (contacts:read)

    Читает контакты: имя, телефон, e-mail, identifier (ID в Вашей системе), пользовательские поля, метки, заметки. Список, поиск, фильтр, контакты онлайн, возможные дубликаты, inbox, через которые можно написать контакту, и синхронизация (/v1/sync/contacts) работают с ним. Вебхуки contact.* тоже требуют его.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/companies: Список компаний
    • GET /v1/companies/search: Поиск компаний
    • GET /v1/companies/{company_id}: Получить компанию
    • POST /v1/contact_inboxes/filter: Найти contact inbox по source ID
    • GET /v1/contacts: Список контактов
    • GET /v1/contacts/active: Контакты, которые сейчас онлайн
    • POST /v1/contacts/filter: Фильтр контактов
    • GET /v1/contacts/search: Поиск контактов
    • GET /v1/contacts/{contact_id}: Получить контакт
    • GET /v1/contacts/{contact_id}/contactable_inboxes: Inbox, через которые можно написать контакту
    • GET /v1/contacts/{contact_id}/labels: Метки контакта
    • GET /v1/contacts/{contact_id}/merge_suggestions: Возможные дубликаты контакта
    • GET /v1/contacts/{contact_id}/notes: Список заметок
    • GET /v1/contacts/{contact_id}/notes/{note_id}: Получить заметку
    • GET /v1/search/contacts: Поиск контактов (общий поиск)
    • GET /v1/sync/contacts: Синхронизация контактов

    Пример:

    curl "https://api.clomni.ai/v1/contacts/search?q=crm-10422" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/sync/contacts?updated_since=2026-11-10T00:00:00Z&limit=100" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Менять контакты (contacts:write)

    Создаёт и обновляет контакты, объединяет два контакта, пишет метки и заметки, привязывает контакт к inbox. В PATCH поле custom_attributes объединяется с прежними значениями, неотправленные ключи не удаляются. Для удаления нужен contacts:delete.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: contacts:read.

    Endpoint:

    • POST /v1/actions/contact_merge: Объединить два контакта
    • POST /v1/companies: Создать компанию
    • PATCH /v1/companies/{company_id}: Изменить компанию
    • POST /v1/contacts: Создать контакт
    • PATCH /v1/contacts/{contact_id}: Изменить контакт
    • DELETE /v1/contacts/{contact_id}/avatar: Удалить фото контакта
    • POST /v1/contacts/{contact_id}/contact_inboxes: Привязать контакт к inbox
    • POST /v1/contacts/{contact_id}/destroy_custom_attributes: Удалить пользовательские поля контакта
    • POST /v1/contacts/{contact_id}/labels: Записать метки контакта
    • POST /v1/contacts/{contact_id}/notes: Создать заметку
    • PATCH /v1/contacts/{contact_id}/notes/{note_id}: Изменить заметку
    • DELETE /v1/contacts/{contact_id}/notes/{note_id}: Удалить заметку

    Пример:

    curl -X POST "https://api.clomni.ai/v1/contacts" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "Leyla Hasanova", "email": "[email protected]", "phone_number": "+994501234567", "identifier": "crm-10422", "custom_attributes": {"customer_tier": "gold"}}'
    curl -X PATCH "https://api.clomni.ai/v1/contacts/981" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"custom_attributes": {"customer_tier": "platinum"}}'
  4. 4

    Импортировать контакты (contacts:import)

    Массово импортирует контакты из CSV: файл передаётся как multipart/form-data в поле import_file, импорт идёт в фоне. Чтобы создавать контакты по одному, достаточно contacts:write.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • POST /v1/contacts/import: Импорт контактов из CSV

    Пример:

    curl -X POST "https://api.clomni.ai/v1/contacts/import" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -F "[email protected]"
  5. 5

    Удалять контакты (contacts:delete)

    Удаляет контакт вместе с его диалогами, отменить нельзя. Удаление компании тоже идёт через этот scope.

    • Риск: высокий.
    • Проверка: проходит review и проверяется внимательнее. Нужны подробное объяснение и короткое видео функции, целевой срок 2 рабочих дня.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • DELETE /v1/companies/{company_id}: Удалить компанию
    • DELETE /v1/contacts/{contact_id}: Удалить контакт

    Пример:

    curl -X DELETE "https://api.clomni.ai/v1/contacts/981" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Видеть метки (labels:read)

    Читает список меток. Чтобы показывать метки диалогов и контактов и строить фильтры.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/labels: Список меток
    • GET /v1/labels/{label_id}: Получить метку

    Пример:

    curl "https://api.clomni.ai/v1/labels" \
  -H "Authorization: Bearer clomni_pat_xxx"
  7. 7

    Менять метки (labels:write)

    Создаёт, меняет и удаляет метки. Поставить метку на диалог или контакт этим scope нельзя: для этого нужен conversations:write или contacts:write.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: labels:read.

    Endpoint:

    • POST /v1/labels: Создать метку
    • PATCH /v1/labels/{label_id}: Изменить метку
    • DELETE /v1/labels/{label_id}: Удалить метку

    Пример:

    curl -X POST "https://api.clomni.ai/v1/labels" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "vip", "description": "Ключевые клиенты", "color": "#ff9f1c", "show_on_sidebar": true}'
  8. 8

    Видеть готовые ответы (canned_responses:read)

    Читает готовые ответы: короткий код и текст. Чтобы в своей панели предлагать операторам готовые ответы.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/canned_responses: Список готовых ответов

    Пример:

    curl "https://api.clomni.ai/v1/canned_responses" \
  -H "Authorization: Bearer clomni_pat_xxx"
  9. 9

    Менять готовые ответы (canned_responses:write)

    Создаёт, меняет и удаляет готовые ответы. Например, автоматически обновлять их из Вашей базы знаний.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: canned_responses:read.

    Endpoint:

    • POST /v1/canned_responses: Создать готовый ответ
    • PATCH /v1/canned_responses/{canned_response_id}: Изменить готовый ответ
    • DELETE /v1/canned_responses/{canned_response_id}: Удалить готовый ответ

    Пример:

    curl -X POST "https://api.clomni.ai/v1/canned_responses" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"short_code": "privet", "content": "Здравствуйте! Чем можем помочь?"}'
  10. 10

    Видеть пользовательские поля (custom_attributes:read)

    Читает определения пользовательских полей: ключ, название, тип, допустимые значения, поле контакта или диалога. Сами значения приходят в объектах контакта и диалога.

    • Риск: низкий.
    • Проверка: проходит review, scope с низким риском смотрят быстро.
    • Дополнительно даёт: ничего больше.

    Endpoint:

    • GET /v1/custom_attribute_definitions: Список пользовательских полей
    • GET /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Получить пользовательское поле

    Пример:

    curl "https://api.clomni.ai/v1/custom_attribute_definitions?attribute_model=contact_attribute" \
  -H "Authorization: Bearer clomni_pat_xxx"
  11. 11

    Менять пользовательские поля (custom_attributes:write)

    Создаёт, меняет и удаляет пользовательские поля. Например, завести в Clomni ключ для поля из CRM.

    • Риск: средний.
    • Проверка: проходит review. Конкретно напишите, какие данные, когда и зачем Вы используете.
    • Дополнительно даёт: custom_attributes:read.

    Endpoint:

    • POST /v1/custom_attribute_definitions: Создать пользовательское поле
    • PATCH /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Изменить пользовательское поле
    • DELETE /v1/custom_attribute_definitions/{custom_attribute_definition_id}: Удалить пользовательское поле

    Пример:

    curl -X POST "https://api.clomni.ai/v1/custom_attribute_definitions" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"attribute_display_name": "Уровень клиента", "attribute_key": "customer_tier", "attribute_display_type": "list", "attribute_values": ["silver", "gold", "platinum"], "attribute_model": "contact_attribute"}'
  12. 12

    О компаниях

    Endpoint компаний (/v1/companies) открываются scope contacts:* и остаются в каталоге. Раздела «Компании» в панели нет с 5 ноября 2026 года, поэтому не стройте на нём новые интеграции. Надёжнее хранить данные компании в пользовательском поле контакта.

  13. 13

    Связанные статьи

Документ

Платформа для разработчиков: руководство v1.0 · 41 стр. Открыть Скачать