Connecting your own system (CRM, website, your own dashboard, AI, BI) to Clomni: which path and scopes to choose, creating an app on developer.clomni.ai, tokens, OAuth, endpoint examples, webhooks, the test channel, review, errors and limits.

Articles from this document

• Developer platform: what it is and which way to choose developer.clomni.ai is for connecting your own software (CRM, website, your own panel, BI) to Clomni through the API. There are three ways: a personal API key (Profile Settings › API access, for for the WhatsApp API only), an internal app (for your own workspace, with scopes and review) and a public app (an app other Clomni accounts connect with OAuth). You connect a ready-made app without code on the Settings › Workspace settings › Apps page.
• Create an app on developer.clomni.ai: step by step On developer.clomni.ai press “Sign in with Clomni”, accept the Developer Terms, and with “New app” choose a name, a workspace and scopes. In the app's settings enter the privacy policy, support email, company and tax ID (VOEN), and send the scopes for review. Once at least one scope is approved, create a token in the “Credentials” section. To create an app you need to be an administrator in the workspace.
• Which scopes you need: scopes and endpoints by what you want to do Find what you want to do: pull messages into a CRM or warehouse, WhatsApp notifications, your own AI bot, the Clomni AI agent on your site, Power BI reports, exports, campaigns, call records, flows, agent management, webhooks and more. For each: the minimal scopes, risk, review and the main endpoints. Rule: ask only for the scopes you need, and the review is faster.
• Tokens and authentication in the Developer API Every request goes to https://api.clomni.ai/v1 with the Authorization: Bearer <token> header. A token belongs to one workspace, and the address has no workspace number. An internal app uses a personal access token (clomni_pat_, “Credentials” › “Create token”, 30-365 days) or a 1-hour app token (clomni_at_) received with client_id and client_secret. Check a token with GET /v1/me. A token is shown only once.
• Public app and OAuth: how other accounts connect your app Other Clomni accounts connect a public app with OAuth: the app sends the administrator to https://my.clomni.co/oauth/developer/authorize, the administrator chooses a workspace on the consent screen and presses “Allow”, and the app exchanges the returned code for a 1-hour access token and a 90-day refresh token with POST /v1/oauth/token. PKCE (S256) and state are required, and the redirect URI must match character for character.
• Using Developer API endpoints: examples, pagination, idempotency An endpoint is a method and a path, for example GET https://api.clomni.ai/v1/conversations. All endpoints and the scopes they need are in the API reference on developer.clomni.ai. Regular lists are paginated with page (conversations in pages of 25, contacts in pages of 15). To copy data into your own database, /v1/sync/* is paginated with updated_since and next_cursor. Send an Idempotency-Key when you retry a POST.
• App webhooks and events: setup, topics, signature verification In the app's “Webhooks” section enter an https URL, choose the topics and save the whsec_ secret. Clomni sends webhook.verify to the URL: your server must return the challenge within 5 seconds. Every request is signed with HMAC-SHA256 and carries the webhook-id, webhook-timestamp and webhook-signature headers (Standard Webhooks). Your server must answer 2xx within 5 seconds, otherwise Clomni sends it again 7 times.
• Test channel: try your app without real customers In the portal's “Test channel” section press “Create test channel” next to the workspace: an API channel named “Developer test channel” appears in the workspace. POST https://api.clomni.ai/v1/test_channel/messages writes a message as a customer, and webhooks, the event feed and automation see it as a real message. Replies go nowhere. messages:send or conversations:write work here before review too.
• Review: checking scopes and rejection reasons Every scope is checked by a Clomni team member (review). In the review form you write for each scope, in at least 100 characters, what you will do, which feature uses it and which fields you store, and once: the use case, the retention period and the test steps. There are four decisions: approved, partially approved, changes requested, rejected. A rejected scope comes with a code from R01 to R12.
• Developer API errors and request limits An error response has the form { error: { code, message, required_scopes, request_id } }: check code in your code. 401 is a token problem, 403 insufficient_scope says a scope is missing, and 429 rate_limited says a limit was exceeded. Limits: 300 requests a minute per token, 600 per app, 60 for /sync/* and sending messages, 20 for /oauth/token. On 429 wait for Retry-After, and do not retry 400, 401, 403, 404 or 422 responses.
• Apps in the dashboard: connecting an app, permissions and removing it On the Settings › Workspace settings › Apps page, “Catalog” shows ready-made apps approved by Clomni, and “Connected apps” shows the ones connected to the workspace. On an app's page press “Connect”, choose the workspace on the consent screen, read the permissions and press “Allow”. To remove an app, choose “Remove” in “Connected apps”: the app loses access at once. Only an administrator can connect and remove apps.
• Scopes and endpoints: workspace, agents, teams workspace:read, workspace:write, billing:read, audit_logs:read, agents:read, agents:manage, teams:read, teams:write: what each scope allows, its risk, review and what it also grants, and the 18 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: inboxes and channels inboxes:read, inboxes:write, channels:read, channels:manage: what each scope allows, its risk, review and what it also grants, and the 12 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: conversations and messages conversations:read, conversations:write, conversations:assign, conversations:delete, messages:read, messages:send, messages:send.template, messages:delete, notes:write: what each scope allows, its risk, review and what it also grants, and the 42 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: contacts, labels, custom attributes, canned responses contacts:read, contacts:write, contacts:import, contacts:delete, labels:read, labels:write, canned_responses:read, canned_responses:write, custom_attributes:read, custom_attributes:write: what each scope allows, its risk, review and what it also grants, and the 45 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: reports, CSAT, SLA reports:read, csat:read, sla:read, sla:write: what each scope allows, its risk, review and what it also grants, and the 32 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: campaigns, flows, automations campaigns:read, campaigns:write, campaigns:send, flows:read, flows:write, flows:publish, automations:read, automations:write, automations:publish: what each scope allows, its risk, review and what it also grants, and the 39 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: AI agents, knowledge base, help center 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: what each scope allows, its risk, review and what it also grants, and the 63 endpoints they open (method, /v1 path, what it does), with curl examples.
• Scopes and endpoints: calls, webhooks, events, exports calls:read, webhooks:read, webhooks:write, events:read, exports:run: what each scope allows, its risk, review and what it also grants, and the 6 endpoints they open (method, /v1 path, what it does), with curl examples.
• Recipe: sync contacts with your CRM Keep Clomni contacts in step with your CRM: scopes contacts:read, contacts:write, custom_attributes:read. Load everything once with GET /v1/sync/contacts, then fetch changes with updated_since and get them right away with the contact.created and contact.updated webhooks. Put the CRM ID in identifier and write back with POST /v1/contacts and PATCH /v1/contacts/{contact_id}.
• Recipe: send WhatsApp notifications and templates from your website Send verification codes, order and delivery notifications from your website or system through a WhatsApp Business API (Cloud) number. Scopes messages:send.template, messages:send, channels:read, messages:read. GET /v1/whatsapp/channels, GET /v1/whatsapp/templates, POST /v1/whatsapp/messages, message.updated for status. A QR number cannot send through this API.
• Recipe: AI agent answers, the knowledge base and your own bot Three jobs: get answers from the Clomni AI agent on your own site (ai_agents:read, ai_agents:ask, POST /v1/ai_agents/{ai_agent_id}/ask), keep the knowledge base up to date automatically (knowledge:write, POST /v1/knowledge) and connect your own AI bot to Clomni conversations (messages:read, messages:send, conversations:assign, the message.created webhook). Costs come from the AI credit.
• Recipe: export your history and keep it in sync Get the conversation, message and contact history in one file (exports:run, POST /v1/exports, GET /v1/exports/{export_id}, gzip JSONL), then fetch only what changes with the sync endpoints (GET /v1/sync/messages, /sync/conversations, /sync/contacts) and webhooks. Limits: 1 export at a time, 6 per 24 hours. For report numbers use reports:read.
• Recipe: show Clomni conversations in your own dashboard Show Clomni conversations in your company's own internal dashboard: list (GET /v1/conversations), messages, replies (POST /v1/conversations/{conversation_id}/messages), private notes, status, assignment and live updates by webhook. The "Clomni in my own panel" preset: conversations:read, conversations:write, conversations:assign, messages:read, messages:send, notes:write and more.