Clomni

Which scopes you need: scopes and endpoints by what you want to do

Last updated: 11 November 2026 · 27 min read

A scope says what an app is allowed to do. Find what you want to do in this article: next to it you see which scopes to ask for, the risk, what the review looks at and which endpoints to call. You create the app on developer.clomni.ai, see Create an app on developer.clomni.ai: step by step.

Steps

  1. 1

    The main rule: ask only for the scopes you need

    Every scope is checked on its own. The reviewer looks at whether each scope is tied to the feature you describe and asks why you need write if reading would do. An unneeded scope is rejected with "R01: this permission is not needed for the feature you describe".

    Why fewer scopes help:

    • the review is faster: each scope needs its own explanation of at least 100 characters, a high risk scope also needs a video, and low risk scopes are looked at quickly;
    • if a token leaks, the damage stays within those scopes;
    • the administrator connecting a public app sees clearly on the consent screen what the app will do.

    How to choose:

    • If reading is enough, do not ask for write. write and manage grant the read of the same resource, so a token with contacts:write can read contacts too.
    • If you use webhooks, ask for the topic's read scope (for example contacts:read) explicitly: when you pick a topic, the portal checks that the read scope itself is approved.
    • send, delete, publish, assign and run grant nothing else. For example, messages:send does not allow reading messages.
    • You can add a scope later: a Live app stays Live, the old scopes keep working and only the new scope goes to review. In a public app a new scope does not reach existing installations by itself; the administrator has to connect the app again.
    • Remove scopes you do not need: removing needs no review and takes effect at once.
    • Before the review, try things on your workspace's test channel: messages:send and conversations:write work there before their review. See Test channel: try your app without real customers.
  2. 2

    What risk and review mean

    • Low risk: no customer personal data, configuration or totals. For example reports:read, labels:read.
    • Medium risk: reads customer data or message text, or changes internal data only. For example conversations:read, contacts:write.
    • High risk: sends to customers, deletes, exports in bulk, changes access or live AI, flow or rule settings. For example messages:send, exports:run, agents:manage.

    Every scope goes through review, low risk ones too. Low risk scopes are looked at quickly. High risk needs a detailed explanation and a short video of the feature; the target is 2 working days. In a public app every scope goes through review as well. More: Review: checking scopes and rejection reasons.

  3. 3

    Presets

    When creating an app you can pick a preset: it selects the scopes for you, and you then remove the ones you do not need. You do not have to keep every scope in a preset.

    • "Clomni in my own panel": conversations:read, conversations:write, conversations:assign, messages:read, messages:send, notes:write, contacts:read, contacts:write, inboxes:read, agents:read, teams:read, labels:read, canned_responses:read, webhooks:write.
    • "CRM sync": contacts:read, contacts:write, custom_attributes:read, conversations:read, messages:read, webhooks:write.
    • "BI and reporting": reports:read, csat:read, conversations:read, agents:read, teams:read, inboxes:read.
    • "Data export": exports:run, events:read.
    • "AI management": ai_agents:read, ai_agents:write, ai_agents:train, knowledge:read, knowledge:write, ai_logs:read.
  4. 4

    1. Pull messages and conversations into another system

    You copy conversations and messages into your own database for a warehouse, an archive or analytics. Load everything once with the sync endpoints, then fetch only what changed with updated_since. Add the message.created webhook to get new messages right away.

    • Minimal scopes: conversations:read, messages:read.
    • Add if needed: contacts:read (if you also need the contact's phone and email); events:read (to recover events missed while your server was down).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/sync/conversations: Sync conversations
    • GET /v1/sync/messages: Sync messages
    • GET /v1/conversations/{conversation_id}/messages: List messages in a conversation

    More: Recipe: export your history and keep it in sync, Scopes and endpoints: conversations and messages.

  5. 5

    2. Move the whole history once

    When moving to another system or keeping an archive, you get conversations, messages and contacts in one file. The export is built in the background and the file link works for 1 hour. An export is not an ongoing sync: for later changes use the sync path above.

    • Minimal scopes: exports:run.
    • Add if needed: events:read (to catch events after the export, together with each topic's read scope).
    • Risk: high (exports:run). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • POST /v1/exports: Start an export
    • GET /v1/exports/{export_id}: Get an export

    More: Recipe: export your history and keep it in sync, Scopes and endpoints: calls, webhooks, events, exports.

  6. 6

    3. Keep contacts in sync with your CRM

    You keep contacts aligned between Clomni and the CRM: the CRM ID goes into the contact's identifier, changes come through sync and webhooks, and the CRM writes back to Clomni. If data only flows from Clomni to the CRM, do not ask for contacts:write.

    • Minimal scopes: contacts:read, contacts:write, custom_attributes:read.
    • Add if needed: conversations:read (if the CRM shows the conversation list); messages:read (if the CRM shows the message text).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/sync/contacts: Sync contacts
    • GET /v1/contacts/search: Search contacts
    • POST /v1/contacts: Create a contact
    • PATCH /v1/contacts/{contact_id}: Update a contact
    • GET /v1/custom_attribute_definitions: List custom attribute definitions

    More: Recipe: sync contacts with your CRM, Scopes and endpoints: contacts, labels, custom attributes, canned responses.

  7. 7

    4. Send WhatsApp notifications and verification codes from your website or system

    You send order, delivery and verification code messages from a WhatsApp Business API (Cloud) number. If the customer has not written in the last 24 hours, only an approved template goes out. A QR-linked number cannot send through this API. If you only send text inside an open window and never a template, messages:send is enough instead of messages:send.template.

    • Minimal scopes: messages:send.template.
    • Add if needed: channels:read (to find channel_id through the API; the ID is also shown in the dashboard); messages:read (to check message status and the 24 hour window, and for the message.* webhooks); messages:send (if you send text together with fallback_template).
    • Risk: high (messages:send.template). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/whatsapp/channels: List WhatsApp numbers
    • GET /v1/whatsapp/templates: List approved WhatsApp templates
    • GET /v1/whatsapp/messages/window: Check the 24 hour window for a number
    • POST /v1/whatsapp/messages: Send a WhatsApp message to a number
    • GET /v1/whatsapp/messages/{message_id}: Get a WhatsApp message's status

    More: Recipe: send WhatsApp notifications and templates from your website, Scopes and endpoints: conversations and messages.

  8. 8

    5. Reply in an open conversation from your own system

    Your system writes into the customer's conversation, for example an order status. The message goes out on the conversation's channel: WhatsApp, Instagram, Messenger, email, chat. Sending happens in the background and the result arrives with the message.updated webhook. A message sent through the API shows under the token owner's name.

    • Minimal scopes: messages:send, conversations:read.
    • Add if needed: messages:read (to read the chat before replying and for the status webhook).
    • Risk: high (messages:send). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/conversations/search: Search conversations
    • POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note
    • POST /v1/conversations/{conversation_id}/messages/{message_id}/retry: Retry a failed message

    More: Recipe: show Clomni conversations in your own dashboard, Scopes and endpoints: conversations and messages.

  9. 9

    6. Connect your own AI bot to Clomni conversations

    Your bot gets new messages by webhook, writes the reply into the conversation and hands the conversation to an agent or a team when it cannot help. A bot can also be connected with just a webhook URL, without a developer app: see "Connect your own bot to a channel (agent bot)". Clomni's own AI agent needs no code at all.

    • Minimal scopes: messages:read, messages:send, conversations:assign.
    • Add if needed: conversations:write (to change the conversation status: pending while the bot talks, open when handing over); notes:write (to leave a private note for agents); contacts:read (to know the customer's name and custom attributes).
    • Risk: high (messages:send). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/conversations/{conversation_id}/messages: List messages in a conversation
    • POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note
    • POST /v1/conversations/{conversation_id}/toggle_status: Change a conversation's status
    • POST /v1/conversations/{conversation_id}/assignments: Assign a conversation

    More: Recipe: AI agent answers, the knowledge base and your own bot, Connect your own bot to a channel (agent bot).

  10. 10

    7. Use the Clomni AI agent on your own website or app

    You ask the AI agent built in Clomni a question and show the answer in your own product. The agent answers with the same instructions and knowledge base and writes nothing into any conversation. Every answer is charged to the workspace's AI credit.

    • Minimal scopes: ai_agents:read, ai_agents:ask.
    • Add if needed: billing:read (to watch the remaining AI credit).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/ai_agents: List AI agents
    • POST /v1/ai_agents/{ai_agent_id}/ask: Ask an AI agent
    • GET /v1/ai_credits: Get the AI credit balance

    More: Recipe: AI agent answers, the knowledge base and your own bot, Scopes and endpoints: AI agents, knowledge base, help center.

  11. 11

    8. Keep the AI agent's knowledge base up to date automatically

    When a policy, price or product page on your site changes, your system adds the new link or file to the knowledge base, removes the old one and writes FAQs. A document is read in the background and can take a few minutes.

    • Minimal scopes: knowledge:write, ai_agents:read.
    • Add if needed: ai_agents:train (to add FAQs and check them with test runs).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/knowledge: List knowledge base documents
    • POST /v1/knowledge: Add a document or link
    • DELETE /v1/knowledge/{document_id}: Delete a knowledge base document
    • POST /v1/ai_agent_faqs: Create a FAQ entry

    More: Recipe: AI agent answers, the knowledge base and your own bot, Scopes and endpoints: AI agents, knowledge base, help center.

  12. 12

    9. Monitor the AI agent's quality

    You pull the questions the agent could not answer, answer reviews and results into your own dashboard or report. To test the agent regularly with test questions, add ai_agents:train; test runs use AI credit.

    • Minimal scopes: ai_logs:read, ai_agents:read.
    • Add if needed: ai_agents:train (to run test questions).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/ai_agents/{ai_agent_id}/gaps: List questions an AI agent could not answer
    • GET /v1/ai_agents/{ai_agent_id}/reviews: List AI answer reviews
    • GET /v1/ai_agents/{ai_agent_id}/results: Get an AI agent's results
    • POST /v1/ai_agents/{ai_agent_id}/test_runs: Start a test run

    More: Scopes and endpoints: AI agents, knowledge base, help center.

  13. 13

    10. Pull reports into Power BI or another BI tool

    You pull conversation counts, first response and resolution times, totals per agent, inbox and team into your BI tool. Totals hold no customer personal data, so reports:read is low risk. To show names, read the agent, team and inbox lists. If you need a row per conversation, add the sync path (the first want).

    • Minimal scopes: reports:read, agents:read, teams:read, inboxes:read.
    • Add if needed: csat:read (if you also need satisfaction ratings); sla:read (to show SLA breaches).
    • Risk: low. All low risk, the review is quick.

    Main endpoints:

    • GET /v1/reports: Get a report time series
    • GET /v1/reports/summary: Get report totals
    • GET /v1/reports/agents: Get report totals per agent
    • GET /v1/summary_reports/team: Get the summary report per team
    • GET /v1/csat_survey_responses/metrics: Get CSAT totals

    More: Scopes and endpoints: reports, CSAT, SLA, Recipe: export your history and keep it in sync.

  14. 14

    11. Show Clomni conversations in your own agent dashboard

    Your agents read the customer chat inside your own internal system, reply, resolve and assign. When creating the app, pick the "Clomni in my own panel" preset and remove what you do not need.

    • Minimal scopes: conversations:read, conversations:write, conversations:assign, messages:read, messages:send.
    • Add if needed: notes:write (for private notes); agents:read (for the list of agents to assign); teams:read (to assign to a team); canned_responses:read (for picking canned responses).
    • Risk: high (messages:send). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/conversations: List conversations
    • GET /v1/conversations/{conversation_id}/messages: List messages in a conversation
    • POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note
    • POST /v1/conversations/{conversation_id}/toggle_status: Change a conversation's status
    • POST /v1/conversations/{conversation_id}/assignments: Assign a conversation

    More: Recipe: show Clomni conversations in your own dashboard, Scopes and endpoints: conversations and messages.

  15. 15

    12. Prepare and send campaigns

    You create the campaign from your system as a draft, then send it and read the results. If you only prepare drafts and a person sends from the dashboard, do not ask for campaigns:send and create with enabled: false.

    • Minimal scopes: campaigns:write, campaigns:send.
    • Add if needed: labels:read (to choose the audience by label); inboxes:read (to choose the inbox the campaign goes from).
    • Risk: high (campaigns:send). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • POST /v1/campaigns: Create a campaign
    • POST /v1/campaigns/{campaign_id}/publish: Publish a campaign
    • GET /v1/campaign_results: List campaign results
    • GET /v1/campaign_results/{campaign_result_id}/contacts: List a campaign's recipients and their status

    More: Scopes and endpoints: campaigns, flows, automations.

  16. 16

    13. Write call records into your CRM

    You pull the log of phone and WhatsApp calls (direction, status, length, the agent who answered) into the CRM. If you need the data the moment a call ends, with its recording and transcript, set up the workspace's call webhooks instead of a developer app.

    • Minimal scopes: calls:read.
    • Add if needed: conversations:read (to find the conversation a call belongs to).
    • Risk: high (calls:read). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/voice_calls: List phone calls
    • GET /v1/whatsapp_calls: List WhatsApp calls
    • GET /v1/whatsapp_calls/{call_id}: Get a WhatsApp call

    More: Scopes and endpoints: calls, webhooks, events, exports, Call webhooks: send your calls to your own system.

  17. 17

    14. Manage help center articles

    The customer help site (portal) is not in any Clomni package since 5 November 2026 and is not shown in the dashboard. The help_center:* scopes stay in the catalogue, but do not tie new integrations to them. If the goal is answering customer questions automatically, keep the knowledge base up to date (the want above).

    • Minimal scopes: knowledge:write, ai_agents:read.
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/knowledge: List knowledge base documents
    • POST /v1/knowledge: Add a document or link

    More: Scopes and endpoints: AI agents, knowledge base, help center.

  18. 18

    15. Manage and switch on flows from code

    You create, check and switch on flows and read their statistics. There is no endpoint that starts a flow for a given customer: a trigger (keyword, event), an agent, the AI agent or the mobile app (Clomni.startFlow) starts it. If you only need statistics, flows:read is enough.

    • Minimal scopes: flows:write, flows:publish.
    • Risk: high (flows:publish). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • GET /v1/flows: List flows
    • GET /v1/flows/{flow_id}/check: Check a flow for problems
    • POST /v1/flows/{flow_id}/publish: Turn a flow on or off
    • GET /v1/flows/{flow_id}/analytics/funnel: Get a flow's step funnel

    More: Scopes and endpoints: campaigns, flows, automations.

  19. 19

    16. Keep automation rules in code

    You create and change rules from your system. Create them with active: false: the rule stays a draft and automations:publish is not needed. If switching rules on is also your job, add automations:publish.

    • Minimal scopes: automations:write.
    • Add if needed: automations:publish (to switch rules on and delete them).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/automation_rules: List automation rules
    • POST /v1/automation_rules: Create an automation rule
    • PATCH /v1/automation_rules/{automation_rule_id}: Update an automation rule

    More: Scopes and endpoints: campaigns, flows, automations.

  20. 20

    17. Manage agents and teams from an HR system

    When someone joins you invite them as an agent and add them to teams and inboxes; when they leave you remove them from the workspace. If you only read the lists, agents:read and teams:read are enough.

    • Minimal scopes: agents:manage, teams:write.
    • Add if needed: inboxes:write (to add agents to inboxes and remove them).
    • Risk: high (agents:manage). The review needs a detailed explanation and a short video of the feature.

    Main endpoints:

    • POST /v1/agents: Invite an agent
    • PATCH /v1/agents/{agent_id}: Change an agent's role or availability
    • DELETE /v1/agents/{agent_id}: Remove an agent from the workspace
    • POST /v1/teams/{team_id}/team_members: Add agents to a team
    • POST /v1/inbox_members: Add agents to an inbox

    More: Scopes and endpoints: workspace, agents, teams.

  21. 21

    18. Get live notifications by webhook

    Clomni sends a request to your server the moment a new message, a new conversation, a status change or a contact change happens. You set the webhook URL on the developer portal, in the app's "Webhooks" section. Each topic needs its own read scope: messages:read for message.*, conversations:read for conversation.*, contacts:read for contact.*. Ask only for the scopes of the topics you use.

    • Minimal scopes: messages:read.
    • Add if needed: conversations:read (for the conversation.* topics); contacts:read (for the contact.* topics); events:read (to fetch missed events from the feed within 30 days).
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/events: List events

    More: App webhooks and events: setup, topics, signature verification, Scopes and endpoints: calls, webhooks, events, exports.

  22. 22

    19. Get alerted when a channel drops

    You check regularly whether a WhatsApp number or another channel is connected and raise an alert in your own monitoring. One low risk scope is enough.

    • Minimal scopes: channels:read.
    • Add if needed: inboxes:read (to show inbox names).
    • Risk: low. All low risk, the review is quick.

    Main endpoints:

    • GET /v1/whatsapp/channels: List WhatsApp numbers
    • GET /v1/inboxes/{inbox_id}/health: Get the channel's health

    More: Scopes and endpoints: inboxes and channels.

  23. 23

    20. Leave a private note for agents from your order system

    When an order, payment or delivery changes, your system writes a note into the conversation that the customer never sees. The agent sees the situation while replying. notes:write is low risk and sends nothing to the customer.

    • Minimal scopes: notes:write, conversations:read.
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/conversations/search: Search conversations
    • POST /v1/conversations/{conversation_id}/messages: Send a message or add a private note

    More: Scopes and endpoints: conversations and messages.

  24. 24

    21. Bulk import contacts

    You upload a CSV file from an old system or a spreadsheet in one request and the import runs in the background. If you create and update contacts one by one, you need contacts:write, not contacts:import.

    • Minimal scopes: contacts:import.
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • POST /v1/contacts/import: Import contacts from a CSV file

    More: Scopes and endpoints: contacts, labels, custom attributes, canned responses.

  25. 25

    22. Copy the audit log into a security system

    You read who changed what and when on a schedule and keep it in your security or compliance system.

    • Minimal scopes: audit_logs:read.
    • Risk: medium. In the review, say for each scope which data you use and why.

    Main endpoints:

    • GET /v1/audit_logs: List audit log entries

    More: Scopes and endpoints: workspace, agents, teams.

  26. 26

    What the API cannot do

    These are closed to developer tokens on purpose. A request to such an endpoint returns 403 endpoint_not_available.

    • creating and deleting a workspace, changing the package and billing;
    • reading channel secrets and connecting channels through the API (channels:manage has no endpoint of its own);
    • agent bots and their tokens, integrations and their OAuth authorizations;
    • profile, password, access tokens, signing in as another user;
    • the workspace's own webhooks: a developer app has its own webhook with topics;
    • bulk actions, notifications and each user's personal screens;
    • placing calls from the API;
    • the SSO company portal, AI apps (MCP) settings and tokens, managing developer apps themselves;
    • WhatsApp bulk sending (bulk_messages): it lives in the separate WhatsApp API that works with a profile API key, see Bulk sending with the WhatsApp API (bulk_messages);
    • starting a flow in a given conversation.
  27. 27

    Related articles

Document

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