> ## Documentation Index
> Fetch the complete documentation index at: https://docs.notifique.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# RCS Instances

> Create and provision branded RCS agents in your workspace to send with your brand identity.

<Tip>
  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).
</Tip>

## 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

```mermaid theme={null}
flowchart LR
  A[POST /instances] --> B[DRAFT]
  B --> C[PATCH agentProfile]
  C --> D[POST .../submit]
  D --> E{Review}
  E -->|Approved| F[ACTIVE]
  E -->|Pending| G[SUBMITTED / standby]
  F --> H[Send with from]
```

1. **DRAFT** — instance created; edit name, `displayName`, and `agentProfile` freely
2. **SUBMITTED / VERIFICATION\_PENDING / LAUNCH\_PENDING** — awaiting review (`awaitingPartner: true`, `standby: true` on submit)
3. **ACTIVE** — agent approved; can send with `from`
4. **REJECTED** — fix profile and submit again

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

## 1. Create instance

```http theme={null}
POST /v1/rcs/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```

```json theme={null}
{
  "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

```http theme={null}
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:

```json theme={null}
{
  "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**:

```json theme={null}
{
  "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.

<Note>
  `instanceId` in the body still works as a legacy alias, but prefer **`from`** (id, instance name, or slug).
</Note>

<Note>
  Inactive instance returns **503** (`RCS_INSTANCE_NOT_ACTIVE`). Missing instance returns **404** (`RCS_INSTANCE_NOT_FOUND`).
</Note>

## API Key restriction

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

## Common errors

<AccordionGroup>
  <Accordion title="409 RCS_SLUG_TAKEN">
    `slug` already exists in this workspace. Choose another or omit to auto-generate.
  </Accordion>

  <Accordion title="409 RCS_PROFILE_LOCKED">
    Active agent in carrier review. Direct edits to the published profile require a new review cycle via `pendingAgentProfile`.
  </Accordion>

  <Accordion title="409 RCS_REVISION_IN_PROGRESS">
    A revision is already in progress. Wait for approval or rejection before another PATCH.
  </Accordion>

  <Accordion title="403 PLAN_LIMIT_INSTANCES">
    Instance limit for your plan reached. Upgrade or remove unused instances.
  </Accordion>

  <Accordion title="503 RCS_INSTANCE_NOT_ACTIVE">
    Agent not yet approved. Check `onboardingStatus` and `awaitingPartner`.
  </Accordion>
</AccordionGroup>

## Next steps

* [Quick Start](/en/rcs-api/como-funciona/quick-start): first send
* [API Key scopes](/en/rcs-api/como-funciona/escopos-da-api-key): instance permissions
* API reference (RCS tab): instance endpoints with examples