Skip to main content
Each scope is a door on your key: send, query, cancel, or manage agents — open only what you need.
Each scope unlocks one type of RCS operation. Use only what your integration needs.

​
How to send the key

Recommended
Alternative
The API Key belongs to one workspace. You cannot access another workspace with the same key.

​
Common combinations

Send only

rcs:send

Send and query

rcs:send, rcs:read

With scheduling

rcs:send, rcs:cancel

Full message flow

rcs:send, rcs:read, rcs:cancel

Manage agents

rcs:instances:list, rcs:instances:create, rcs:instances:delete

Full integration

All RCS scopes above
Empty scope list on creation = ADMIN access. In production, always restrict.

​
Available scopes

Send immediate or scheduled RCS to 1–500 numbers per request. Types: BASIC, CARD, CAROUSEL, FILE, template. Use from for the branded agent (id or name).Endpoint: POST /v1/rcs/messages
List and query RCS sends, and list/detail inbound messages.Endpoints: GET /v1/rcs/messages, GET /v1/rcs/messages/:id, GET /v1/rcs/inbound, GET /v1/rcs/inbound/:id
Cancel queued or scheduled message. Only with status QUEUED or SCHEDULED. Credits refunded when applicable.Endpoint: POST /v1/rcs/messages/:id/cancel
List workspace RCS instances and query agent detail.Endpoints: GET /v1/rcs/instances, GET /v1/rcs/instances/:instanceId
Create instance, update agent profile, and submit for provisioning.Endpoints: POST /v1/rcs/instances, PATCH /v1/rcs/instances/:instanceId, POST /v1/rcs/instances/:instanceId/submit
Remove RCS instance from workspace.Endpoint: DELETE /v1/rcs/instances/:instanceId

​
Instance restriction

If the API Key has instanceIds set, it only accesses and sends through listed instances. Empty list = access to all.

​
Common errors

Check Authorization: Bearer sk_... and that the key was not deleted in the dashboard.
Insufficient credits (INSUFFICIENT_CREDITS) or expired plan (WORKSPACE_BLOCKED).
Check operation scope. Scheduling depends on plan (PLAN_LIMIT_SCHEDULING). Instance not allowed by key returns FORBIDDEN.
Instance limit for your plan reached when creating agent.
Cancel only with status QUEUED or SCHEDULED. After sent, no cancellation.
Send attempt with instanceId of agent not yet approved.

​
Next steps