Как подключить свою систему (CRM, сайт, свою панель, AI, BI) к Clomni: какой путь и какие scope выбрать, создание приложения на developer.clomni.ai, токены, OAuth, примеры эндпоинтов, вебхуки, тестовый канал, проверка, ошибки и лимиты.

Статьи по документу

• Платформа для разработчиков: что это и какой способ выбрать developer.clomni.ai нужен, чтобы соединить Ваши собственные программы (CRM, сайт, своя панель, BI) с Clomni через API. Есть три способа: личный ключ API («Profile Settings › API access», для только для WhatsApp API), внутреннее приложение (для Вашего workspace, со scope и review) и публичное приложение (public app, которое другие аккаунты Clomni подключают через OAuth). Готовое приложение без кода подключается на странице «Settings › Workspace settings › Apps».
• Создание приложения на developer.clomni.ai: пошагово На developer.clomni.ai нажмите «Sign in with Clomni», примите «Developer Terms», через «New app» выберите название, workspace и scope. В настройках приложения укажите политику конфиденциальности, e-mail поддержки, компанию и ИНН (VOEN), отправьте scope на review. Когда одобрен хотя бы один scope, создайте токен в разделе «Credentials». Чтобы создать приложение, нужно быть администратором workspace.
• Какие scope нужны: scope и endpoint по Вашей задаче Найдите свою задачу: выгрузка сообщений в CRM или хранилище, уведомления WhatsApp, свой AI-бот, AI-агент Clomni на Вашем сайте, отчёты в Power BI, экспорт, кампании, записи звонков, сценарии, управление операторами, вебхуки и другое. Для каждой: минимальные scope, риск, проверка и основные endpoint. Правило: запрашивайте только нужные scope, тогда review проходит быстрее.
• Токены и аутентификация в Developer API Каждый запрос идёт на адрес https://api.clomni.ai/v1 с заголовком Authorization: Bearer <token>, токен привязан к одному workspace, и номер workspace в адресе не пишется. Во внутреннем приложении используется личный токен (clomni_pat_, «Credentials» › «Create token», 30-365 дней) или токен приложения на 1 час (clomni_at_), который получают по client_id и client_secret. Проверьте токен через GET /v1/me. Токен показывается только один раз.
• Public app и OAuth: как другие аккаунты подключают приложение Публичное приложение (public app) другие аккаунты Clomni подключают через OAuth: приложение отправляет администратора на адрес https://my.clomni.co/oauth/developer/authorize, администратор на экране согласия выбирает workspace и нажимает «Allow», приложение обменивает полученный код через POST /v1/oauth/token на access token на 1 час и refresh token на 90 дней. PKCE (S256) и state обязательны, redirect URI должен совпадать буква в букву.
• Работа с эндпоинтами Developer API: примеры, постраничный вывод, idempotency Эндпоинт это метод и путь, например GET https://api.clomni.ai/v1/conversations. Все эндпоинты и нужные scope есть в API reference на developer.clomni.ai. Обычные списки разбиты на страницы через page (диалоги по 25, контакты по 15), а для переноса данных в Вашу базу /v1/sync/* выдаёт страницы через updated_since и next_cursor. Повторяя POST, передавайте Idempotency-Key.
• Вебхуки приложения и события: настройка, темы, проверка подписи В разделе приложения «Webhooks» укажите https URL, выберите темы и сохраните секрет whsec_. Clomni отправляет на URL webhook.verify: сервер должен за 5 секунд вернуть challenge. Каждый запрос подписывается HMAC-SHA256 с заголовками webhook-id, webhook-timestamp и webhook-signature (Standard Webhooks). Сервер должен ответить 2xx за 5 секунд, иначе Clomni отправит запрос повторно 7 раз.
• Тестовый канал: проверка приложения без реальных клиентов В разделе портала «Test channel» рядом с workspace нажмите «Create test channel»: в workspace появится API-канал «Developer test channel». POST https://api.clomni.ai/v1/test_channel/messages пишет сообщение от имени клиента, а вебхуки, лента событий и автоматизация видят его как настоящее. Ответы никуда не уходят. messages:send или conversations:write работают здесь и до review.
• Review: проверка scope и причины отказа Каждый scope проходит проверку сотрудником Clomni (review). В форме review для каждого scope Вы пишете не меньше 100 символов о том, что будете делать, какая функция его использует и какие поля Вы храните, а один раз также сценарий использования, срок хранения и шаги для теста. Решение бывает четырёх видов: одобрено, частично одобрено, нужны исправления, отклонено. Рядом с отклонённым scope стоит код R01-R12.
• Ошибки Developer API и лимиты запросов Ответ с ошибкой имеет вид { error: { code, message, required_scopes, request_id } }: в коде проверяйте code. 401 означает проблему с токеном, 403 insufficient_scope говорит, что не хватает scope, 429 rate_limited означает, что лимит превышен. Лимиты: 300 запросов в минуту на токен, 600 на приложение, 60 для /sync/* и отправки сообщений, 20 для /oauth/token. При 429 подождите время из Retry-After, ответы 400, 401, 403, 404, 422 не повторяйте.
• Страница Apps в панели: подключение приложения, разрешения и отключение На странице «Settings › Workspace settings › Apps» вкладка «Catalog» показывает готовые приложения, одобренные Clomni, а «Connected apps» показывает приложения, подключённые к workspace. На странице приложения нажмите «Connect», на экране согласия выберите workspace, прочитайте разрешения и нажмите «Allow». Чтобы отключить приложение, выберите «Remove» в «Connected apps»: приложение сразу теряет доступ. Подключать и отключать приложения может только администратор.
• Scope и endpoint: workspace, операторы, команды workspace:read, workspace:write, billing:read, audit_logs:read, agents:read, agents:manage, teams:read, teams:write: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 18 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: inbox и каналы inboxes:read, inboxes:write, channels:read, channels:manage: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 12 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: диалоги и сообщения conversations:read, conversations:write, conversations:assign, conversations:delete, messages:read, messages:send, messages:send.template, messages:delete, notes:write: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 42 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: контакты, метки, пользовательские поля, готовые ответы contacts:read, contacts:write, contacts:import, contacts:delete, labels:read, labels:write, canned_responses:read, canned_responses:write, custom_attributes:read, custom_attributes:write: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 45 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: отчёты, CSAT, SLA reports:read, csat:read, sla:read, sla:write: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 32 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: кампании, сценарии, автоматизация campaigns:read, campaigns:write, campaigns:send, flows:read, flows:write, flows:publish, automations:read, automations:write, automations:publish: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 39 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: AI-агенты, база знаний, центр помощи ai_agents:read, ai_agents:write, ai_agents:train, ai_agents:publish, ai_agents:ask, knowledge:read, knowledge:write, ai_logs:read, help_center:read, help_center:write: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 63 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Scope и endpoint: звонки, вебхуки, события, экспорт calls:read, webhooks:read, webhooks:write, events:read, exports:run: что разрешает каждый scope, риск, проверка, что даёт дополнительно и 6 endpoint, которые они открывают (метод, путь /v1, что делает), с примерами curl.
• Рецепт: синхронизация контактов с CRM Держать контакты Clomni в соответствии с CRM: scope contacts:read, contacts:write, custom_attributes:read. Сначала загрузите всё через GET /v1/sync/contacts, затем забирайте изменения через updated_since и получайте их сразу вебхуками contact.created и contact.updated. ID из CRM записывайте в identifier, в Clomni пишите через POST /v1/contacts и PATCH /v1/contacts/{contact_id}.
• Рецепт: уведомления и шаблоны WhatsApp с Вашего сайта Отправлять с сайта или из своей системы коды подтверждения, уведомления о заказе и доставке через номер WhatsApp Business API (Cloud). Scope messages:send.template, messages:send, channels:read, messages:read. GET /v1/whatsapp/channels, GET /v1/whatsapp/templates, POST /v1/whatsapp/messages, статус через message.updated. Номер QR через этот API не отправляет.
• Рецепт: ответы AI-агента, база знаний и свой бот Три задачи: получать ответы AI-агента Clomni на своём сайте (ai_agents:read, ai_agents:ask, POST /v1/ai_agents/{ai_agent_id}/ask), автоматически обновлять базу знаний (knowledge:write, POST /v1/knowledge) и подключать своего AI-бота к диалогам Clomni (messages:read, messages:send, conversations:assign, вебхук message.created). Расход списывается с AI-кредита.
• Рецепт: экспорт истории и постоянная синхронизация Получить историю диалогов, сообщений и контактов одним файлом (exports:run, POST /v1/exports, GET /v1/exports/{export_id}, gzip JSONL), а затем забирать только изменения через endpoint синхронизации (GET /v1/sync/messages, /sync/conversations, /sync/contacts) и вебхуки. Лимиты: 1 экспорт одновременно, 6 за 24 часа. Для цифр отчётов используйте reports:read.
• Рецепт: диалоги Clomni в Вашей собственной панели Показывать диалоги Clomni во внутренней панели компании: список (GET /v1/conversations), сообщения, ответы (POST /v1/conversations/{conversation_id}/messages), внутренние заметки, статус, назначение и обновление в реальном времени через вебхуки. Готовый набор «Clomni в моей панели»: conversations:read, conversations:write, conversations:assign, messages:read, messages:send, notes:write и другие.