Clomni

Scope и endpoint: inbox и каналы

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

Scope для настроек inbox, участников, рабочих часов и состояния каналов. Inbox (в панели «канал») это копия канала в workspace: два номера WhatsApp это два отдельных inbox.

Шаги

  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

    Видеть inbox (inboxes:read)

    Читает inbox и их настройки: название, тип канала, рабочие часы, автоназначение, участников. Inbox это копия канала в workspace, например каждый номер WhatsApp отдельный inbox. Секреты и токены каналов никогда не возвращаются. Список одобренных шаблонов WhatsApp тоже открывается этим scope.

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

    Endpoint:

    • GET /v1/inbox_members/{inbox_id}: Операторы inbox
    • GET /v1/inboxes: Список inbox
    • GET /v1/inboxes/{inbox_id}: Получить inbox
    • GET /v1/inboxes/{inbox_id}/assignable_agents: Операторы, которых можно назначить в inbox
    • GET /v1/whatsapp/templates: Одобренные шаблоны WhatsApp. Открывается и через messages:send.template

    Пример:

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

    Менять настройки inbox (inboxes:write)

    Меняет настройки inbox: название, приветствие, автоназначение, рабочие часы и операторов inbox. Если в теле есть объект channel, нужен ещё и channels:manage.

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

    Endpoint:

    • POST /v1/inbox_members: Добавить операторов в inbox
    • PATCH /v1/inbox_members: Заменить операторов inbox
    • DELETE /v1/inbox_members: Убрать операторов из inbox
    • PATCH /v1/inboxes/{inbox_id}: Изменить настройки inbox
    • PATCH /v1/working_hours/{working_hour_id}: Изменить рабочие часы

    Пример:

    curl -X PATCH "https://api.clomni.ai/v1/inboxes/5" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"enable_auto_assignment": true}'
    curl -X POST "https://api.clomni.ai/v1/inbox_members" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": 5, "user_ids": [12]}'
  4. 4

    Видеть состояние канала (channels:read)

    Читает состояние канала: подключён, отключён, статус QR, качество номера WhatsApp. Также возвращает номера WhatsApp workspace и их channel_id. Подходит, чтобы поднимать тревогу в своей системе, когда номер отключается.

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

    Endpoint:

    • GET /v1/inboxes/{inbox_id}/health: Состояние канала
    • GET /v1/whatsapp/channels: Номера WhatsApp

    Пример:

    curl "https://api.clomni.ai/v1/whatsapp/channels" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/inboxes/5/health" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Управлять каналами (channels:manage)

    Предназначен для подключения, отключения и переподключения каналов. Сейчас у этого scope нет своего endpoint: он нужен только когда в теле PATCH /v1/inboxes/{inbox_id} есть объект channel. Каналы подключайте в панели.

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

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

Документ

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