Scope и endpoint: звонки, вебхуки, события, экспорт

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

Шаги

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

   Читать звонки (calls:read)

   Читает журнал звонков: телефонные звонки и звонки WhatsApp (направление, статус, длительность, диалог, ответивший оператор). По каталогу записи и расшифровки тоже относятся к этому scope, поэтому риск высокий.

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

   Endpoint:

   • GET /v1/voice_calls: Телефонные звонки
   • GET /v1/whatsapp_calls: Звонки WhatsApp
   • GET /v1/whatsapp_calls/{call_id}: Получить звонок WhatsApp

   Пример:

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

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

3. 3

   Видеть вебхуки (webhooks:read)

   Предназначен для просмотра подписки вебхука и журнала доставки. Вебхук настраивается на портале разработчика, в разделе приложения «Вебхуки», журнал виден там же.

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

   У этого scope нет своего endpoint в API /v1.

4. 4

   Управлять вебхуками (webhooks:write)

   Предназначен для управления подпиской вебхука. Адрес и темы выбираются на портале разработчика. Каждая тема требует свой scope на чтение: conversations:read для conversation.*, messages:read для message.*, contacts:read для contact.*.

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

   У этого scope нет своего endpoint в API /v1.

5. 5

   Читать ленту событий (events:read)

   Читает ленту событий за последние 30 дней: чтобы восстановить пропущенные вебхуки или опрашивать вместо вебхуков. Нужен и scope на чтение каждой темы, один events:read возвращает пустой список. События пишутся, только пока в workspace есть активный токен разработчика или установка.

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

   Endpoint:

   • GET /v1/events: Лента событий

   Пример:

   curl "https://api.clomni.ai/v1/events?types=message.created,contact.updated&limit=100" \
     -H "Authorization: Bearer clomni_pat_xxx"

6. 6

   Массовый экспорт (exports:run)

   Массово выгружает диалоги, сообщения и контакты в один файл (gzip JSONL). В workspace одна задача одновременно и 6 за 24 часа. Ссылка на файл работает 1 час. В review укажите цель, целевую систему, частоту и срок хранения файла.

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

   Endpoint:

   • POST /v1/exports: Начать экспорт
   • GET /v1/exports/{export_id}: Получить экспорт

   Пример:

   curl -X POST "https://api.clomni.ai/v1/exports" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"resources": ["conversations", "messages", "contacts"], "since": "2026-01-01T00:00:00Z", "until": "2026-11-01T00:00:00Z"}'

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

7. 7

   События звонков в реальном времени

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

8. 8

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

   • Какие scope нужны: scope и endpoint по Вашей задаче
   • Рецепт: экспорт истории и постоянная синхронизация
   • Рецепт: синхронизация контактов с CRM
   • Работа с эндпоинтами Developer API: примеры, постраничный вывод, idempotency