Scopes and endpoints: conversations and messages

Last updated: 11 November 2026 · 11 min read

Scopes for reading, changing and assigning conversations and for sending messages. A conversation's number in the API ({conversation_id}) is the number the dashboard shows. In sync objects, though, id is the internal ID and the dashboard number is in number.

Steps

1
How to read this article
- Paths follow https://api.clomni.ai/v1: GET /v1/agents means https://api.clomni.ai/v1/agents. Paths have no workspace ID, because a token belongs to one workspace.
- Every request carries the Authorization: Bearer clomni_pat_xxx header. How to get a token: Tokens and authentication in the Developer API.
- Risk: low (no personal data), medium (reads customer data or changes internal data), high (sends to customers, deletes, bulk exports, changes live settings).
- Every scope goes through review, in public apps too. More: Review: checking scopes and rejection reasons.
- "Also grants": write and manage grant the read of the same resource. send, delete, publish, assign and run grant nothing.
- When an endpoint lists several scopes, any one of them is enough. Without the scope the API answers 403 insufficient_scope with required_scopes in the body.
- Every POST takes an Idempotency-Key header, so a repeated request is not run twice.
2
Read conversations (conversations:read)
Reads conversations: status, assignee, team, labels, custom attributes, last message. List, search, filter, counts and sync (/v1/sync/conversations) work with it. The conversation.* webhooks need it too. For the full message text you need messages:read as well.
- Risk: medium.
- Review: goes through review. Say exactly which data you use with it, when and why.
- Also grants: nothing else.
Endpoints:
- GET /v1/contacts/{contact_id}/conversations: List a contact's conversations
- GET /v1/conversations: List conversations
- POST /v1/conversations/filter: Filter conversations
- GET /v1/conversations/meta: Count conversations by assignment
- GET /v1/conversations/search: Search conversations
- GET /v1/conversations/{conversation_id}: Get a conversation
- GET /v1/conversations/{conversation_id}/labels: List a conversation's labels
- GET /v1/conversations/{conversation_id}/participants: List a conversation's participants
- GET /v1/search/conversations: Search conversations (global search)
- GET /v1/sync/conversations: Sync conversations
Example:
```
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
Edit conversations (conversations:write)
Changes a conversation's status (open, resolved, pending, snoozed), priority, labels and custom attributes, starts new conversations, marks them read or unread. Starting a conversation with a first message also needs messages:send. This scope works on the test channel before its review.
- Risk: medium.
- Review: goes through review. Say exactly which data you use with it, when and why.
- Also grants: conversations:read.
Endpoints:
- POST /v1/conversations: Start a conversation
- PATCH /v1/conversations/{conversation_id}: Update a conversation
- POST /v1/conversations/{conversation_id}/custom_attributes: Set a conversation's custom attributes
- POST /v1/conversations/{conversation_id}/labels: Set a conversation's labels
- POST /v1/conversations/{conversation_id}/mute: Mute a conversation
- POST /v1/conversations/{conversation_id}/toggle_priority: Change a conversation's priority
- POST /v1/conversations/{conversation_id}/toggle_status: Change a conversation's status
- POST /v1/conversations/{conversation_id}/toggle_typing_status: Show or hide the typing indicator
- POST /v1/conversations/{conversation_id}/unmute: Unmute a conversation
- POST /v1/conversations/{conversation_id}/unread: Mark a conversation as unread
- POST /v1/conversations/{conversation_id}/update_last_seen: Mark a conversation as read
- POST /v1/test_channel/messages: Simulate a customer message (test channel). messages:send or conversations:write is enough, and works on the test channel before the review
Example:
```
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": ["order", "vip"]}'
```
4
Assign conversations (conversations:assign)
Assigns a conversation to an agent or a team, adds participants, takes a conversation for the token's owner. It does not grant reading: the conversation list needs conversations:read.
- Risk: medium.
- Review: goes through review. Say exactly which data you use with it, when and why.
- Also grants: nothing else.
Endpoints:
- POST /v1/conversations/{conversation_id}/assignments: Assign a conversation
- POST /v1/conversations/{conversation_id}/participants: Add participants to a conversation
- PATCH /v1/conversations/{conversation_id}/participants: Replace a conversation's participants
- DELETE /v1/conversations/{conversation_id}/participants: Remove participants from a conversation
- POST /v1/conversations/{conversation_id}/take: Assign a conversation to the token's user
Example:
```
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
Delete conversations (conversations:delete)
Deletes a conversation. It cannot be undone, so it is high risk. To archive, resolve the conversation instead (conversations:write).
- Risk: high.
- Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
- Also grants: nothing else.
Endpoints:
- DELETE /v1/conversations/{conversation_id}: Delete a conversation
Example:
```
curl -X DELETE "https://api.clomni.ai/v1/conversations/1042" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
6
Read messages (messages:read)
Reads message text and files: a conversation's messages, its files, message search, message sync, a WhatsApp message's status and the 24 hour window. The message.created and message.updated webhooks need this scope too.
- Risk: medium.
- Review: goes through review. Say exactly which data you use with it, when and why.
- Also grants: nothing else.
Endpoints:
- GET /v1/conversations/{conversation_id}/attachments: List a conversation's files
- GET /v1/conversations/{conversation_id}/messages: List messages in a conversation
- GET /v1/search/messages: Search messages
- GET /v1/sync/messages: Sync messages
- GET /v1/whatsapp/messages/window: Check the 24 hour window for a number
- GET /v1/whatsapp/messages/{message_id}: Get a WhatsApp message's status
Example:
```
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
Send messages (messages:send)
Sends messages to customers on any channel: replies in a conversation, edits, reactions, retrying a failed message, WhatsApp text to a number. Sending does not grant reading: to see the conversation you also need messages:read. A conversation message with private: true is a private note and needs notes:write; one with template_params needs messages:send.template. This scope works on the test channel before its review.
- Risk: high.
- Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days. Also say who creates the messages (a person, AI, an automation), roughly how many go out a day and how consent for marketing messages is collected.
- Also grants: nothing else.
Endpoints:
- POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note. private: true needs notes:write, template_params needs messages:send.template
- PATCH /v1/conversations/{conversation_id}/messages/{message_id}: Report a message's delivery status (API channel)
- PATCH /v1/conversations/{conversation_id}/messages/{message_id}/edit_content: Edit a sent message
- POST /v1/conversations/{conversation_id}/messages/{message_id}/reaction: React to a message
- POST /v1/conversations/{conversation_id}/messages/{message_id}/retry: Retry a failed message
- POST /v1/test_channel/messages: Simulate a customer message (test channel). messages:send or conversations:write is enough, and works on the test channel before the review
- POST /v1/whatsapp/messages: Send a WhatsApp message to a number. template needs messages:send.template, fallback_template needs both messages:send and messages:send.template
Example:
```
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": "Hello, your order goes to the courier today.", "content_attributes": {"client_echo_id": "crm-7f3a9c"}}'
```
8
Send template messages (messages:send.template)
Sends WhatsApp template messages: works outside the 24 hour window too, and Meta charges for every template. Required when POST /v1/whatsapp/messages has template, or a conversation message has template_params. With fallback_template it is needed together with messages:send. It also opens the list of approved templates.
- Risk: high.
- Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days. Also say who creates the messages (a person, AI, an automation), roughly how many go out a day and how consent for marketing messages is collected.
- Also grants: nothing else.
Endpoints:
- POST /v1/whatsapp/messages: Send a WhatsApp message to a number. template needs messages:send.template, fallback_template needs both messages:send and messages:send.template
- GET /v1/whatsapp/templates: List approved WhatsApp templates. Also opens with inboxes:read
Example:
```
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
Delete messages (messages:delete)
Marks a message as deleted and removes its files. On WhatsApp QR the message is also revoked on the customer's phone.
- Risk: high.
- Review: goes through review and gets a closer look. A detailed explanation and a short video of the feature are needed; the target is 2 working days.
- Also grants: nothing else.
Endpoints:
- DELETE /v1/conversations/{conversation_id}/messages/{message_id}: Delete a message
Example:
```
curl -X DELETE "https://api.clomni.ai/v1/conversations/1042/messages/51240" \
  -H "Authorization: Bearer clomni_pat_xxx"
```
10
Write private notes (notes:write)
Adds a private note to a conversation (private: true). The customer never sees it. Your CRM, order system or own bot uses it to leave a note for agents. Low risk.
- Risk: low.
- Review: goes through review; low risk scopes are looked at quickly.
- Also grants: nothing else.
Endpoints:
- POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note. private: true needs notes:write, template_params needs messages:send.template
Example:
```
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 customer, payment is late.", "private": true}'
```
11
Related articles

Document

Developer platform: guide v1.0 · 41 pages Open Download

Scopes and endpoints: conversations and messages

Steps

How to read this article

Read conversations (conversations:read)

Edit conversations (conversations:write)

Assign conversations (conversations:assign)

Delete conversations (conversations:delete)

Read messages (messages:read)

Send messages (messages:send)

Send template messages (messages:send.template)

Delete messages (messages:delete)

Write private notes (notes:write)

Related articles

Document