Рецепт: диалоги Clomni в Вашей собственной панели

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

Шаги

1. 1

   Что Вы получите

   • Список открытых диалогов в Вашей панели, со счётчиками и фильтрами.
   • Сообщения диалога, ответы и внутренние заметки, которые клиент не видит.
   • Закрытие и повторное открытие диалогов, назначение оператору или команде.
   • Обновление новых сообщений и статусов в реальном времени через вебхуки.
2. 2

   Нужные scope

   При создании приложения выберите готовый набор «Clomni в моей панели» и уберите лишнее:

   • conversations:read (средний): список диалогов и сам диалог;
   • conversations:write (средний): статус, приоритет, метки;
   • conversations:assign (средний): назначение оператору или команде;
   • messages:read (средний): текст и файлы сообщений, вебхуки message.*;
   • messages:send (высокий): ответ клиенту;
   • notes:write (низкий): внутренние заметки;
   • contacts:read, contacts:write (средний): данные контакта;
   • inboxes:read, agents:read, teams:read, labels:read, canned_responses:read (низкий): фильтры и списки выбора.

   Владелец токена это администратор workspace, поэтому API возвращает все inbox и все диалоги. Что показывать операторам, ограничивайте в своей панели сами. Ответ, отправленный через API, виден в диалоге от имени владельца токена.

3. 3

   1. Список диалогов

   GET /v1/conversations возвращает страницы по 25, по последней активности. Параметры: status (open, resolved, pending, snoozed, all, по умолчанию open), assignee_type (me, unassigned, assigned, all), inbox_id, team_id, labels[], q, page.

   curl "https://api.clomni.ai/v1/conversations?status=open&assignee_type=all&page=1" \
     -H "Authorization: Bearer clomni_pat_xxx"

   Счётчики лежат в data.meta (mine_count, assigned_count, unassigned_count, all_count), страница в data.payload. id диалога это номер из панели, и {conversation_id} во всех путях диалогов это этот номер.

4. 4

   2. Сообщения диалога

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

   Ответ содержит последние 20 сообщений от старых к новым. Для более старых передайте самый маленький id в before: ?before=55120. Пустой payload означает начало истории. message_type: 0 от клиента, 1 от оператора или API, 2 системное событие, 3 шаблон. status: sent, delivered, read, failed.

5. 5

   3. Ответ и внутренняя заметка

   curl -X POST "https://api.clomni.ai/v1/conversations/1042/messages" \
     -H "Authorization: Bearer clomni_pat_xxx" \
     -H "Content-Type: application/json" \
     -d '{"content": "Здравствуйте, Лейла. Ваш заказ доставят сегодня.", "content_attributes": {"client_echo_id": "panel-7f3a9c"}}'

   • Канал отправляет сообщение в фоне, результат позже виден в status (вебхук message.updated).
   • Запишите своё уникальное значение в content_attributes.client_echo_id: в течение 24 часов запрос с тем же значением в том же диалоге не создаёт второе сообщение. При повторе значение не меняйте.
   • Для внутренней заметки передайте "private": true, scope notes:write. Клиент её не видит.
   • В диалоге WhatsApp Cloud can_reply: false означает, что 24-часовое окно закрыто: нужен шаблон, см. Рецепт: уведомления и шаблоны WhatsApp с Вашего сайта.
6. 6

   4. Статус и назначение

   Закрыть или открыть заново (conversations:write):

   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"}'

   Назначить (conversations:assign): {"assignee_id": 12} оператору, {"team_id": 3} команде, {"assignee_id": null} снимает оператора.

   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}'

   Списки операторов и команд дают GET /v1/agents и GET /v1/teams, готовые ответы GET /v1/canned_responses.

7. 7

   5. Обновление в реальном времени

   Вместо обновления списка каждые несколько секунд настройте вебхук на портале разработчика. Темы для такой панели: message.created, message.updated, conversation.created, conversation.updated, conversation.status_changed, conversation.assigned. Доставка гарантирована хотя бы один раз, но Ваш сервер тоже может остановиться: храните время последнего успеха и при восстановлении вызывайте GET /v1/sync/messages?updated_since=<время>. См. Вебхуки приложения и события: настройка, темы, проверка подписи.

8. 8

   Частые ошибки

   • Список обновляется каждые несколько секунд и упирается в лимит. Используйте вебхуки.
   • GET /v1/conversations листают постранично, чтобы скопировать все диалоги. Для этого есть GET /v1/sync/conversations.
   • Ответ повторяется без client_echo_id или Idempotency-Key, и клиент получает два сообщения.
   • status: sent принимают за «доставлено». Если сообщение не ушло, позже оно станет failed, причина в content_attributes.external_error.
   • При 422 читают только error.code. Собственные ошибки проверки у endpoint пока в старом формате: {"error": "..."} или {"message": "..."}.
   • Забывают про лимит отправки: для POST /v1/conversations/{conversation_id}/messages это 60 запросов в минуту на токен.

   Все endpoint диалогов и сообщений: Scope и endpoint: диалоги и сообщения.