Clomni

Scope и endpoint: кампании, сценарии, автоматизация

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

Scope для кампаний, сценариев (flow) и правил автоматизации. У всех трёх одно правило: write готовит черновик, а шаг, который доходит до клиентов (отправка, включение), требует отдельного scope send или publish.

Шаги

  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

    Видеть кампании (campaigns:read)

    Читает кампании, их версии, результаты и статусы получателей.

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

    Endpoint:

    • GET /v1/campaign_results: Результаты кампаний
    • GET /v1/campaign_results/{campaign_result_id}: Результат кампании
    • GET /v1/campaign_results/{campaign_result_id}/contacts: Получатели кампании и их статусы
    • GET /v1/campaigns: Список кампаний
    • GET /v1/campaigns/{campaign_id}: Получить кампанию
    • GET /v1/campaigns/{campaign_id}/versions: Версии кампании

    Пример:

    curl "https://api.clomni.ai/v1/campaigns" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/campaign_results" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Черновики кампаний (campaigns:write)

    Создаёт и меняет черновики кампаний, отменяет неопубликованные изменения, восстанавливает старую версию, удаляет кампанию. Внимание: если в POST /v1/campaigns нет enabled: false, кампания создаётся активной и нужен ещё campaigns:send. В PATCH с enabled: true или scheduled_at тоже нужен campaigns:send.

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

    Endpoint:

    • POST /v1/campaigns: Создать кампанию
    • PATCH /v1/campaigns/{campaign_id}: Изменить кампанию
    • DELETE /v1/campaigns/{campaign_id}: Удалить кампанию
    • POST /v1/campaigns/{campaign_id}/revert: Отменить неопубликованные изменения
    • POST /v1/campaigns/{campaign_id}/versions/{version}/restore: Восстановить версию кампании

    Пример:

    curl -X POST "https://api.clomni.ai/v1/campaigns" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Ноябрьская скидка", "inbox_id": 5, "enabled": false, "scheduled_at": 1794200000, "audience": [{"type": "Label", "id": 14}], "template_params": {"name": "november_sale", "language": "az", "category": "MARKETING", "processed_params": {"body": {"1": "15%"}}}}'
  4. 4

    Отправлять кампании (campaigns:send)

    Отправляет или планирует кампанию. Клиентам уходит массовая рассылка, поэтому риск высокий: в review укажите объём и как получено согласие.

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

    Endpoint:

    • POST /v1/campaigns/{campaign_id}/publish: Опубликовать кампанию

    Пример:

    curl -X POST "https://api.clomni.ai/v1/campaigns/9/publish" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Видеть сценарии (flows:read)

    Читает сценарии, папки, версии, статистику, воронку шагов и контакты, прошедшие сценарий, проверяет сценарий на проблемы.

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

    Endpoint:

    • GET /v1/flow_folders: Список папок сценариев
    • GET /v1/flow_report: Отчёт по сценариям
    • GET /v1/flow_stats: Статистика всех сценариев
    • GET /v1/flows: Список сценариев
    • GET /v1/flows/{flow_id}: Получить сценарий
    • GET /v1/flows/{flow_id}/analytics: Статистика сценария
    • GET /v1/flows/{flow_id}/analytics/contacts: Контакты, прошедшие сценарий
    • GET /v1/flows/{flow_id}/analytics/funnel: Воронка шагов сценария
    • GET /v1/flows/{flow_id}/check: Проверить сценарий на проблемы
    • GET /v1/flows/{flow_id}/versions: Версии сценария
    • GET /v1/flows/{flow_id}/versions/{version_id}: Получить версию сценария

    Пример:

    curl "https://api.clomni.ai/v1/flows" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/flows/31/check" \
  -H "Authorization: Bearer clomni_pat_xxx"
  6. 6

    Черновики сценариев (flows:write)

    Создаёт и меняет черновики сценариев, копирует их, переносит в папки, управляет папками. Поле status в теле считается публикацией и требует ещё flows:publish.

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

    Endpoint:

    • POST /v1/flow_folders: Создать папку сценариев
    • PATCH /v1/flow_folders/{flow_folder_id}: Изменить папку
    • DELETE /v1/flow_folders/{flow_folder_id}: Удалить папку
    • POST /v1/flows: Создать сценарий
    • PATCH /v1/flows/{flow_id}: Изменить сценарий
    • POST /v1/flows/{flow_id}/copy: Копировать сценарий
    • PATCH /v1/flows/{flow_id}/move: Переместить сценарий в папку

    Тело запроса смотрите в API reference на developer.clomni.ai.

  7. 7

    Включать сценарии (flows:publish)

    Включает и выключает сценарий, восстанавливает старую версию, удаляет сценарий. Активный сценарий сам пишет клиентам, поэтому риск высокий. Endpoint, который запускает сценарий в конкретном диалоге, отсутствует: сценарий запускают триггер, оператор, AI-агент или мобильное приложение (Clomni.startFlow).

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

    Endpoint:

    • DELETE /v1/flows/{flow_id}: Удалить сценарий
    • POST /v1/flows/{flow_id}/publish: Включить или выключить сценарий
    • POST /v1/flows/{flow_id}/versions/{version_id}/restore: Восстановить версию сценария

    Тело запроса смотрите в API reference на developer.clomni.ai.

  8. 8

    Видеть автоматизацию (automations:read)

    Читает правила автоматизации: событие, условия, действия и активно ли правило.

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

    Endpoint:

    • GET /v1/automation_rules: Список правил автоматизации
    • GET /v1/automation_rules/{automation_rule_id}: Получить правило

    Пример:

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

    Черновики правил (automations:write)

    Создаёт и меняет правила, не включая их. Если в POST нет active: false, правило создаётся активным и нужен ещё automations:publish. active: true в PATCH тоже требует automations:publish.

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

    Endpoint:

    • POST /v1/automation_rules: Создать правило автоматизации
    • PATCH /v1/automation_rules/{automation_rule_id}: Изменить правило

    Пример:

    curl -X POST "https://api.clomni.ai/v1/automation_rules" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"name": "VIP-диалоги команде продаж", "event_name": "conversation_created", "active": false, "conditions": [{"attribute_key": "customer_tier", "filter_operator": "equal_to", "values": ["gold"], "query_operator": null}], "actions": [{"action_name": "assign_team", "action_params": [3]}]}'
  10. 10

    Включать правила (automations:publish)

    Включает и выключает правила (active в PATCH), копирует и удаляет правило. Копия активного правила тоже активна, поэтому копирование идёт через этот scope.

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

    Endpoint:

    • DELETE /v1/automation_rules/{automation_rule_id}: Удалить правило
    • POST /v1/automation_rules/{automation_rule_id}/clone: Копировать правило автоматизации

    Пример:

    curl -X PATCH "https://api.clomni.ai/v1/automation_rules/6" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"active": true}'
  11. 11

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

Документ

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