RCS Instances

An RCS instance is your brand’s agent in RCS Business Messaging: name, logo, colors, and approval dossier. Once ACTIVE, send by passing from in POST /v1/rcs/messages (instance id or name).

In short

Create a draft with POST /v1/rcs/instances
Fill the agent profile (agentProfile) with PATCH
Submit for approval with POST /v1/rcs/instances/:id/submit
Send with from when status is ACTIVE

Without your own instance, the workspace uses the platform shared sender (when available) or the workspace default instance.

When to create an instance?

Scenario	Need an instance?
Quick sandbox test	No
Campaign with generic sender	Optional
Own brand on RCS (logo, name, approved agent)	Yes
Multiple brands in one workspace	One instance per brand

Provisioning flow

DRAFT — instance created; edit name, displayName, and agentProfile freely
SUBMITTED / VERIFICATION_PENDING / LAUNCH_PENDING — awaiting review (awaitingPartner: true, standby: true on submit)
ACTIVE — agent approved; can send with from
REJECTED — fix profile and submit again

On an ACTIVE agent, profile changes go into review (pendingAgentProfile, revisionStatus: DRAFT). Sending continues with the approved profile until the new revision is accepted.

1. Create instance

POST /v1/rcs/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx

{
  "name": "My Brand RCS",
  "slug": "my-brand",
  "displayName": "My Brand"
}

201 response with onboardingStatus: "DRAFT". Scope: rcs:instances:create. slug is unique per workspace (2–64 chars, lowercase and hyphens). If omitted, it is generated from name.

2. Fill agent profile

Update with PATCH /v1/rcs/instances/:instanceId. Main agentProfile fields:

Field	Required on submit	Description
`brandName`, `displayName`	Yes	Brand name shown on RCS
`description`	Yes	Short agent description
`logoUri`, `heroUri`	Yes	Public https URLs for logo and hero image
`color`	Yes	Brand color in hex (`#1A73E8`)
`hostingRegion`	Yes	`NORTH_AMERICA`, `EUROPE`, or `ASIA_PACIFIC`
`billingCategory`	Yes	`CONVERSATIONAL` or `NON_CONVERSATIONAL`
`agentUseCase`	Yes	`OTP`, `TRANSACTIONAL`, `PROMOTIONAL`, or `MULTI_USE`
`phoneNumbers`, `emails`, `websites`	At least one contact	List with `value` and `label`
`privacy.uri`, `termsConditions.uri`	Yes	Privacy and terms links
`brandContactName`, `brandContactEmailAddress`, `brandWebsiteUrl`	Yes	Brand contact
`brazil.cnpj`, `brazil.legalName`	Yes (Brazil)	14-digit CNPJ and legal name
`brazil.brandAuthorizationAccepted`	Yes (Brazil)	Must be `true`
`launch.*`	Yes	Launch questionnaire (trigger, interactions, opt-out, access instructions)

3. Submit for approval

POST /v1/rcs/instances/:instanceId/submit
Authorization: Bearer sk_live_xxxxx

Incomplete profile returns 400 (RCS_PROFILE_INCOMPLETE). Already active returns 409 (RCS_ALREADY_ACTIVE). Manual review response:

{
  "success": true,
  "data": { "onboardingStatus": "SUBMITTED", "awaitingPartner": true },
  "standby": true,
  "message": "Agent submitted for manual review."
}

4. Send with the instance

When status and onboardingStatus are ACTIVE:

{
  "from": "inst_rcs_abc123",
  "to": ["5511999999999"],
  "type": "card",
  "payload": {
    "cardImage": "https://cdn.example.com/rcs/offer.jpg",
    "cardTitle": "Brand offer",
    "cardMessage": "Exclusive for you.",
    "buttons": [{ "text": "Buy", "url": "https://example.com/buy" }]
  }
}

If from is omitted, the platform uses the workspace default instance (if ACTIVE) or the shared sender.

instanceId in the body still works as a legacy alias, but prefer from (id, instance name, or slug).

Inactive instance returns 503 (RCS_INSTANCE_NOT_ACTIVE). Missing instance returns 404 (RCS_INSTANCE_NOT_FOUND).

API Key restriction

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

Common errors

409 RCS_SLUG_TAKEN

slug already exists in this workspace. Choose another or omit to auto-generate.

409 RCS_PROFILE_LOCKED

Active agent in carrier review. Direct edits to the published profile require a new review cycle via pendingAgentProfile.

409 RCS_REVISION_IN_PROGRESS

A revision is already in progress. Wait for approval or rejection before another PATCH.

403 PLAN_LIMIT_INSTANCES

Instance limit for your plan reached. Upgrade or remove unused instances.

503 RCS_INSTANCE_NOT_ACTIVE

Agent not yet approved. Check onboardingStatus and awaitingPartner.

Next steps

Quick Start: first send
API Key scopes: instance permissions
API reference (RCS tab): instance endpoints with examples

API E-mail

E-mail

Domínios

E-mails recebidos

In short

When to create an instance?

Provisioning flow

1. Create instance

2. Fill agent profile

3. Submit for approval

4. Send with the instance

API Key restriction

Common errors

Next steps

​In short

​When to create an instance?

​Provisioning flow

​1. Create instance

​2. Fill agent profile

​3. Submit for approval

​4. Send with the instance

​API Key restriction

​Common errors

​Next steps

In short

When to create an instance?

Provisioning flow

1. Create instance

2. Fill agent profile

3. Submit for approval

4. Send with the instance

API Key restriction

Common errors

Next steps