Clomni

Scope и endpoint: диалоги и сообщения

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

Scope для чтения, изменения и назначения диалогов и отправки сообщений. Номер диалога в API ({conversation_id}) совпадает с номером в панели. В объектах синхронизации id это внутренний ID, а номер из панели лежит в поле number.

Шаги

  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

    Читать диалоги (conversations:read)

    Читает диалоги: статус, назначение, команду, метки, пользовательские поля, последнее сообщение. С ним работают список, поиск, фильтр, счётчики и синхронизация (/v1/sync/conversations). Вебхуки conversation.* тоже требуют его. Для полного текста сообщений нужен ещё messages:read.

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

    Endpoint:

    • GET /v1/contacts/{contact_id}/conversations: Диалоги контакта
    • GET /v1/conversations: Список диалогов
    • POST /v1/conversations/filter: Фильтр диалогов
    • GET /v1/conversations/meta: Количество диалогов по назначению
    • GET /v1/conversations/search: Поиск диалогов
    • GET /v1/conversations/{conversation_id}: Получить диалог
    • GET /v1/conversations/{conversation_id}/labels: Метки диалога
    • GET /v1/conversations/{conversation_id}/participants: Участники диалога
    • GET /v1/search/conversations: Поиск диалогов (общий поиск)
    • GET /v1/sync/conversations: Синхронизация диалогов

    Пример:

    curl "https://api.clomni.ai/v1/conversations?status=open&assignee_type=unassigned&page=1" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/sync/conversations?updated_since=2026-11-10T00:00:00Z&limit=100" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Менять диалоги (conversations:write)

    Меняет статус диалога (открыт, решён, в ожидании, отложен), приоритет, метки и пользовательские поля, начинает новые диалоги, отмечает их прочитанными или непрочитанными. Чтобы начать диалог с первым сообщением, нужен ещё messages:send. В тестовом канале этот scope работает ещё до review.

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

    Endpoint:

    • POST /v1/conversations: Начать диалог
    • PATCH /v1/conversations/{conversation_id}: Изменить диалог
    • POST /v1/conversations/{conversation_id}/custom_attributes: Записать пользовательские поля диалога
    • POST /v1/conversations/{conversation_id}/labels: Записать метки диалога
    • POST /v1/conversations/{conversation_id}/mute: Отключить звук диалога
    • POST /v1/conversations/{conversation_id}/toggle_priority: Изменить приоритет диалога
    • POST /v1/conversations/{conversation_id}/toggle_status: Изменить статус диалога
    • POST /v1/conversations/{conversation_id}/toggle_typing_status: Индикатор «печатает...»
    • POST /v1/conversations/{conversation_id}/unmute: Включить звук диалога
    • POST /v1/conversations/{conversation_id}/unread: Отметить диалог непрочитанным
    • POST /v1/conversations/{conversation_id}/update_last_seen: Отметить диалог прочитанным
    • POST /v1/test_channel/messages: Симуляция сообщения клиента (тестовый канал). Достаточно messages:send или conversations:write, в тестовом канале работает ещё до review

    Пример:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/toggle_status" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"status": "resolved"}'
    curl -X POST "https://api.clomni.ai/v1/conversations/1042/labels" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"labels": ["заказ", "vip"]}'
  4. 4

    Назначать диалоги (conversations:assign)

    Назначает диалог оператору или команде, добавляет участников, забирает диалог на владельца токена. Чтение не даёт: для списка диалогов нужен conversations:read.

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

    Endpoint:

    • POST /v1/conversations/{conversation_id}/assignments: Назначить диалог
    • POST /v1/conversations/{conversation_id}/participants: Добавить участников в диалог
    • PATCH /v1/conversations/{conversation_id}/participants: Заменить участников диалога
    • DELETE /v1/conversations/{conversation_id}/participants: Убрать участников из диалога
    • POST /v1/conversations/{conversation_id}/take: Взять диалог на владельца токена

    Пример:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"assignee_id": 12}'
    curl -X POST "https://api.clomni.ai/v1/conversations/1042/assignments" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"team_id": 3}'
  5. 5

    Удалять диалоги (conversations:delete)

    Удаляет диалог. Отменить нельзя, поэтому риск высокий. Чтобы убрать в архив, лучше закройте диалог (conversations:write).

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

    Endpoint:

    • DELETE /v1/conversations/{conversation_id}: Удалить диалог

    Пример:

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

    Читать сообщения (messages:read)

    Читает текст и файлы сообщений: сообщения диалога, файлы, поиск, синхронизацию сообщений, статус сообщения WhatsApp и 24-часовое окно. Вебхуки message.created и message.updated тоже требуют этот scope.

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

    Endpoint:

    • GET /v1/conversations/{conversation_id}/attachments: Файлы диалога
    • GET /v1/conversations/{conversation_id}/messages: Сообщения диалога
    • GET /v1/search/messages: Поиск сообщений
    • GET /v1/sync/messages: Синхронизация сообщений
    • GET /v1/whatsapp/messages/window: Проверить 24-часовое окно для номера
    • GET /v1/whatsapp/messages/{message_id}: Статус сообщения WhatsApp

    Пример:

    curl "https://api.clomni.ai/v1/conversations/1042/messages" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/sync/messages?updated_since=2026-11-10T00:00:00Z&limit=100" \
  -H "Authorization: Bearer clomni_pat_xxx"
  7. 7

    Отправлять сообщения (messages:send)

    Отправляет клиенту сообщения в любом канале: ответ в диалоге, правку, реакцию, повтор неудачного сообщения, текст WhatsApp на номер. Отправка не даёт чтения: чтобы видеть диалог, нужен ещё messages:read. Сообщение диалога с private: true это внутренняя заметка, ей нужен notes:write, а сообщению с template_params нужен messages:send.template. В тестовом канале этот scope работает ещё до review.

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

    Endpoint:

    • POST /v1/conversations/{conversation_id}/messages: Отправить сообщение или написать внутреннюю заметку. Для private: true нужен notes:write, для template_params нужен messages:send.template
    • PATCH /v1/conversations/{conversation_id}/messages/{message_id}: Сообщить статус доставки сообщения (API-канал)
    • PATCH /v1/conversations/{conversation_id}/messages/{message_id}/edit_content: Исправить отправленное сообщение
    • POST /v1/conversations/{conversation_id}/messages/{message_id}/reaction: Реакция на сообщение
    • POST /v1/conversations/{conversation_id}/messages/{message_id}/retry: Повторно отправить неудачное сообщение
    • POST /v1/test_channel/messages: Симуляция сообщения клиента (тестовый канал). Достаточно messages:send или conversations:write, в тестовом канале работает ещё до review
    • POST /v1/whatsapp/messages: Отправить сообщение WhatsApp на номер. Для template нужен messages:send.template, для fallback_template нужны messages:send и messages:send.template

    Пример:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Idempotency-Key: 6f1c2a9e-3b7d-4f0a-9c55-0e8b1d2a7f41" \
  -H "Content-Type: application/json" \
  -d '{"content": "Здравствуйте, сегодня Ваш заказ передадут курьеру.", "content_attributes": {"client_echo_id": "crm-7f3a9c"}}'
  8. 8

    Отправлять шаблонные сообщения (messages:send.template)

    Отправляет шаблонные сообщения WhatsApp: работает и вне 24-часового окна, Meta берёт плату за каждый шаблон. Нужен, когда в POST /v1/whatsapp/messages есть template или в сообщении диалога есть template_params. С fallback_template нужен вместе с messages:send. Также открывает список одобренных шаблонов.

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

    Endpoint:

    • POST /v1/whatsapp/messages: Отправить сообщение WhatsApp на номер. Для template нужен messages:send.template, для fallback_template нужны messages:send и messages:send.template
    • GET /v1/whatsapp/templates: Одобренные шаблоны WhatsApp. Открывается и через inboxes:read

    Пример:

    curl "https://api.clomni.ai/v1/whatsapp/templates?channel_id=5" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl -X POST "https://api.clomni.ai/v1/whatsapp/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"channel_id": 5, "phone_number": "+994501234567", "template": {"name": "order_ready", "language": "az", "parameters": {"body": {"1": "Leyla", "2": "A-1042"}}}, "source_reference": "order-A-1042-ready"}'
  9. 9

    Удалять сообщения (messages:delete)

    Помечает сообщение удалённым и удаляет его файлы. В WhatsApp QR сообщение также отзывается на телефоне клиента.

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

    Endpoint:

    • DELETE /v1/conversations/{conversation_id}/messages/{message_id}: Удалить сообщение

    Пример:

    curl -X DELETE "https://api.clomni.ai/v1/conversations/1042/messages/51240" \
  -H "Authorization: Bearer clomni_pat_xxx"
  10. 10

    Писать внутренние заметки (notes:write)

    Пишет в диалог внутреннюю заметку (private: true). Клиент её не видит. CRM, система заказов или Ваш бот оставляют так заметку оператору. Риск низкий.

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

    Endpoint:

    • POST /v1/conversations/{conversation_id}/messages: Отправить сообщение или написать внутреннюю заметку. Для private: true нужен notes:write, для template_params нужен messages:send.template

    Пример:

    curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"content": "CRM: VIP-клиент, оплата задерживается.", "private": true}'
  11. 11

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

Документ

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