Clomni

Scopes and endpoints: inboxes and channels

Last updated: 11 November 2026 · 6 min read

Scopes for inbox settings, members, working hours and channel status. An inbox is one channel's copy in the workspace: two WhatsApp numbers are two separate inboxes.

Steps

  1. 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. 2

    Read inboxes (inboxes:read)

    Reads inboxes and their settings: name, channel type, working hours, auto-assignment, members. An inbox is a channel's copy in the workspace, for example every WhatsApp number is its own inbox. Channel secrets and tokens are never returned. The list of approved WhatsApp templates also opens with this scope.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

    • GET /v1/inbox_members/{inbox_id}: List an inbox's agents
    • GET /v1/inboxes: List inboxes
    • GET /v1/inboxes/{inbox_id}: Get an inbox
    • GET /v1/inboxes/{inbox_id}/assignable_agents: List agents who can be assigned in an inbox
    • GET /v1/whatsapp/templates: List approved WhatsApp templates. Also opens with messages:send.template

    Example:

    curl "https://api.clomni.ai/v1/inboxes" \
  -H "Authorization: Bearer clomni_pat_xxx"
  3. 3

    Edit inbox settings (inboxes:write)

    Changes inbox settings: name, greeting, auto-assignment, working hours and the inbox's agents. If the body has a channel object, channels:manage is needed as well.

    • Risk: medium.
    • Review: goes through review. Say exactly which data you use with it, when and why.
    • Also grants: inboxes:read.

    Endpoints:

    • POST /v1/inbox_members: Add agents to an inbox
    • PATCH /v1/inbox_members: Replace an inbox's agents
    • DELETE /v1/inbox_members: Remove agents from an inbox
    • PATCH /v1/inboxes/{inbox_id}: Update an inbox
    • PATCH /v1/working_hours/{working_hour_id}: Update working hours

    Example:

    curl -X PATCH "https://api.clomni.ai/v1/inboxes/5" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"enable_auto_assignment": true}'
    curl -X POST "https://api.clomni.ai/v1/inbox_members" \
  -H "Authorization: Bearer clomni_pat_xxx" \
  -H "Content-Type: application/json" \
  -d '{"inbox_id": 5, "user_ids": [12]}'
  4. 4

    Read channel status (channels:read)

    Reads channel status: connected, disconnected, QR state, the WhatsApp number's quality. Also returns the workspace's WhatsApp numbers and their channel_id. Good for raising an alert in your own system when a number drops.

    • Risk: low.
    • Review: goes through review; low risk scopes are looked at quickly.
    • Also grants: nothing else.

    Endpoints:

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

    Example:

    curl "https://api.clomni.ai/v1/whatsapp/channels" \
  -H "Authorization: Bearer clomni_pat_xxx"
    curl "https://api.clomni.ai/v1/inboxes/5/health" \
  -H "Authorization: Bearer clomni_pat_xxx"
  5. 5

    Manage channels (channels:manage)

    Meant for connecting, disconnecting and reconnecting channels. Today this scope has no endpoint of its own: it is required only when the body of PATCH /v1/inboxes/{inbox_id} has a channel object. Connect channels in the dashboard.

    • 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: channels:read.
  6. 6

    Related articles

Document

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