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

# Instâncias RCS

> Crie e provisione agentes RCS branded do seu workspace para enviar com a identidade da sua marca.

<Tip>
  Uma **instância RCS** é o **agente da sua marca** no RCS Business Messaging: nome, logo, cores e dossiê de aprovação. Depois de **ACTIVE**, você envia passando `from` no `POST /v1/rcs/messages` (id ou nome da instância).
</Tip>

## Em poucas palavras

* **Crie** o rascunho com `POST /v1/rcs/instances`
* **Preencha** o perfil do agente (`agentProfile`) com `PATCH`
* **Submeta** para aprovação com `POST /v1/rcs/instances/:id/submit`
* **Envie** com `from` quando o status for **ACTIVE**

Sem instância própria, o workspace usa o **remetente compartilhado** da plataforma (quando disponível) ou a **instância padrão** do workspace.

## Quando criar uma instância?

| Cenário                                            | Precisa de instância?       |
| -------------------------------------------------- | --------------------------- |
| Teste rápido no sandbox                            | Não                         |
| Campanha com remetente genérico                    | Opcional                    |
| Marca própria no RCS (logo, nome, agente aprovado) | **Sim**                     |
| Várias marcas no mesmo workspace                   | **Uma instância por marca** |

## Fluxo de provisionamento

```mermaid theme={null}
flowchart LR
  A[POST /instances] --> B[DRAFT]
  B --> C[PATCH agentProfile]
  C --> D[POST .../submit]
  D --> E{Revisão}
  E -->|Aprovado| F[ACTIVE]
  E -->|Pendente| G[SUBMITTED / standby]
  F --> H[Envio com from]
```

1. **DRAFT** — instância criada; edite nome, `displayName` e `agentProfile` livremente
2. **SUBMITTED / VERIFICATION\_PENDING / LAUNCH\_PENDING** — aguardando revisão (`awaitingPartner: true`, `standby: true` na submissão)
3. **ACTIVE** — agente aprovado; pode enviar com `from`
4. **REJECTED** — corrija o perfil e submeta de novo

<Warning>
  Em agente **ACTIVE**, alterações no perfil entram em **revisão** (`pendingAgentProfile`, `revisionStatus: DRAFT`). O envio continua com o perfil aprovado até a nova revisão ser aceita.
</Warning>

## 1. Criar instância

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

```json theme={null}
{
  "name": "Minha Marca RCS",
  "slug": "minha-marca",
  "displayName": "Minha Marca"
}
```

Resposta **201** com `onboardingStatus: "DRAFT"`. Escopo: **`rcs:instances:create`**.

O `slug` é único por workspace (2–64 caracteres, minúsculas e hífens). Se omitir, é gerado a partir do `name`.

## 2. Preencher o perfil do agente

Atualize com `PATCH /v1/rcs/instances/:instanceId`. Campos principais de `agentProfile`:

| Campo                                                             | Obrigatório no submit | Descrição                                                                       |
| ----------------------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------- |
| `brandName`, `displayName`                                        | Sim                   | Nome da marca exibido no RCS                                                    |
| `description`                                                     | Sim                   | Descrição curta do agente                                                       |
| `logoUri`, `heroUri`                                              | Sim                   | URLs públicas (https) da logo e imagem hero                                     |
| `color`                                                           | Sim                   | Cor da marca em hex (`#1A73E8`)                                                 |
| `hostingRegion`                                                   | Sim                   | `NORTH_AMERICA`, `EUROPE` ou `ASIA_PACIFIC`                                     |
| `billingCategory`                                                 | Sim                   | `CONVERSATIONAL` ou `NON_CONVERSATIONAL`                                        |
| `agentUseCase`                                                    | Sim                   | `OTP`, `TRANSACTIONAL`, `PROMOTIONAL` ou `MULTI_USE`                            |
| `phoneNumbers`, `emails`, `websites`                              | Pelo menos um contato | Lista com `value` e `label`                                                     |
| `privacy.uri`, `termsConditions.uri`                              | Sim                   | Links de privacidade e termos                                                   |
| `brandContactName`, `brandContactEmailAddress`, `brandWebsiteUrl` | Sim                   | Contato da marca                                                                |
| `brazil.cnpj`, `brazil.legalName`                                 | Sim (Brasil)          | CNPJ com 14 dígitos e razão social                                              |
| `brazil.brandAuthorizationAccepted`                               | Sim (Brasil)          | Deve ser `true`                                                                 |
| `launch.*`                                                        | Sim                   | Questionário de lançamento (gatilho, interações, opt-out, instruções de acesso) |

Exemplo parcial:

```json theme={null}
{
  "displayName": "Minha Marca",
  "agentProfile": {
    "brandName": "Minha Marca",
    "displayName": "Minha Marca",
    "hostingRegion": "NORTH_AMERICA",
    "billingCategory": "NON_CONVERSATIONAL",
    "agentUseCase": "PROMOTIONAL",
    "description": "Campanhas e avisos promocionais.",
    "color": "#1A73E8",
    "logoUri": "https://cdn.example.com/rcs/logo.png",
    "heroUri": "https://cdn.example.com/rcs/hero.png",
    "phoneNumbers": [{ "value": "+551140028922", "label": "SAC" }],
    "emails": [{ "value": "contato@minhamarca.com", "label": "Suporte" }],
    "privacy": { "uri": "https://minhamarca.com/privacidade" },
    "termsConditions": { "uri": "https://minhamarca.com/termos" },
    "brandContactName": "Maria Silva",
    "brandContactEmailAddress": "maria@minhamarca.com",
    "brandWebsiteUrl": "https://minhamarca.com",
    "brazil": {
      "cnpj": "12345678000199",
      "legalName": "Minha Marca LTDA",
      "brandAuthorizationAccepted": true
    },
    "launch": {
      "contacts": [{ "name": "Maria Silva", "title": "Marketing", "email": "maria@minhamarca.com" }],
      "triggerDescription": "Cliente recebe RCS após opt-in no site.",
      "interactionsDescription": "Botões de resposta e links.",
      "optoutDescription": "Responda SAIR para cancelar.",
      "agentAccessInstructions": "Acesse pelo app Mensagens do Android."
    }
  }
}
```

## 3. Submeter para aprovação

```http theme={null}
POST /v1/rcs/instances/:instanceId/submit
Authorization: Bearer sk_live_xxxxx
```

Se o perfil estiver incompleto, retorna **400** (`RCS_PROFILE_INCOMPLETE`). Se já estiver ativo, **409** (`RCS_ALREADY_ACTIVE`).

Resposta com revisão manual:

```json theme={null}
{
  "success": true,
  "data": { "onboardingStatus": "SUBMITTED", "awaitingPartner": true },
  "standby": true,
  "message": "Agent submitted for manual review."
}
```

## 4. Enviar com a instância

Quando `status` e `onboardingStatus` forem **ACTIVE**:

```json theme={null}
{
  "from": "inst_rcs_abc123",
  "to": ["5511999999999"],
  "type": "card",
  "payload": {
    "cardImage": "https://cdn.example.com/rcs/oferta.jpg",
    "cardTitle": "Oferta da marca",
    "cardMessage": "Exclusivo para você.",
    "buttons": [{ "text": "Comprar", "url": "https://example.com/comprar" }]
  }
}
```

Se `from` for omitido, a plataforma usa a **instância padrão** do workspace (se ACTIVE) ou o remetente compartilhado.

<Note>
  `instanceId` no corpo ainda funciona como alias legado, mas prefira **`from`** (id, nome da instância ou slug).
</Note>

<Note>
  Instância inativa retorna **503** (`RCS_INSTANCE_NOT_ACTIVE`). Instância inexistente retorna **404** (`RCS_INSTANCE_NOT_FOUND`).
</Note>

## Restrição por API Key

Se a chave tiver `instanceIds` preenchido, ela só acessa e envia pelas instâncias listadas. Lista vazia = acesso a todas.

## Erros comuns

<AccordionGroup>
  <Accordion title="409 RCS_SLUG_TAKEN">
    O `slug` já existe neste workspace. Escolha outro ou omita para gerar automaticamente.
  </Accordion>

  <Accordion title="409 RCS_PROFILE_LOCKED">
    Agente já ativo em revisão com a operadora. Alterações diretas no perfil publicado exigem novo ciclo de revisão via `pendingAgentProfile`.
  </Accordion>

  <Accordion title="409 RCS_REVISION_IN_PROGRESS">
    Já há uma revisão em andamento. Aguarde aprovação ou rejeição antes de novo PATCH.
  </Accordion>

  <Accordion title="403 PLAN_LIMIT_INSTANCES">
    Limite de instâncias do plano atingido. Faça upgrade ou remova instâncias não usadas.
  </Accordion>

  <Accordion title="503 RCS_INSTANCE_NOT_ACTIVE">
    O agente ainda não foi aprovado. Confira `onboardingStatus` e `awaitingPartner`.
  </Accordion>
</AccordionGroup>

## Próximos passos

* [Quick Start](/rcs-api/como-funciona/quick-start): primeiro envio
* [Escopos da API Key](/rcs-api/como-funciona/escopos-da-api-key): permissões de instância
* Referência da API (aba RCS): endpoints de instâncias com exemplos