> ## 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.
# Instancias RCS
> Cree y aprovisione agentes RCS de marca en su workspace para enviar con la identidad de su marca.
Una **instancia RCS** es el **agente de su marca** en RCS Business Messaging: nombre, logo, colores y expediente de aprobación. Una vez **ACTIVE**, envíe pasando `from` en `POST /v1/rcs/messages` (id o nombre de la instancia).
## En pocas palabras
* **Cree** el borrador con `POST /v1/rcs/instances`
* **Complete** el perfil del agente (`agentProfile`) con `PATCH`
* **Envíe** a aprobación con `POST /v1/rcs/instances/:id/submit`
* **Envíe mensajes** con `from` cuando el estado sea **ACTIVE**
Sin instancia propia, el workspace usa el **remitente compartido** de la plataforma (cuando esté disponible) o la **instancia predeterminada** del workspace.
## ¿Cuándo crear una instancia?
| Escenario | ¿Necesita instancia? |
| --------------------------------------------------- | --------------------------- |
| Prueba rápida en sandbox | No |
| Campaña con remitente genérico | Opcional |
| Marca propia en RCS (logo, nombre, agente aprobado) | **Sí** |
| Varias marcas en un workspace | **Una instancia por marca** |
## Flujo de aprovisionamiento
```mermaid theme={null}
flowchart LR
A[POST /instances] --> B[DRAFT]
B --> C[PATCH agentProfile]
C --> D[POST .../submit]
D --> E{Revisión}
E -->|Aprobado| F[ACTIVE]
E -->|Pendiente| G[SUBMITTED / standby]
F --> H[Envío con from]
```
1. **DRAFT** — instancia creada; edite nombre, `displayName` y `agentProfile` libremente
2. **SUBMITTED / VERIFICATION\_PENDING / LAUNCH\_PENDING** — en espera de revisión (`awaitingPartner: true`, `standby: true` al enviar)
3. **ACTIVE** — agente aprobado; puede enviar con `from`
4. **REJECTED** — corrija el perfil y envíe de nuevo
En un agente **ACTIVE**, los cambios de perfil entran en **revisión** (`pendingAgentProfile`, `revisionStatus: DRAFT`). El envío continúa con el perfil aprobado hasta que se acepte la nueva revisión.
## 1. Crear instancia
```http theme={null}
POST /v1/rcs/instances
Content-Type: application/json
Authorization: Bearer sk_live_xxxxx
```
```json theme={null}
{
"name": "Mi Marca RCS",
"slug": "mi-marca",
"displayName": "Mi Marca"
}
```
Respuesta **201** con `onboardingStatus: "DRAFT"`. Ámbito: **`rcs:instances:create`**.
El `slug` es único por workspace (2–64 caracteres, minúsculas y guiones). Si se omite, se genera a partir del `name`.
## 2. Completar el perfil del agente
Actualice con `PATCH /v1/rcs/instances/:instanceId`. Campos principales de `agentProfile`:
| Campo | Obligatorio al enviar | Descripción |
| ----------------------------------------------------------------- | --------------------- | ----------------------------------------------------------------------------------------- |
| `brandName`, `displayName` | Sí | Nombre de marca mostrado en RCS |
| `description` | Sí | Descripción corta del agente |
| `logoUri`, `heroUri` | Sí | URLs públicas https de logo e imagen hero |
| `color` | Sí | Color de marca en hex (`#1A73E8`) |
| `hostingRegion` | Sí | `NORTH_AMERICA`, `EUROPE` o `ASIA_PACIFIC` |
| `billingCategory` | Sí | `CONVERSATIONAL` o `NON_CONVERSATIONAL` |
| `agentUseCase` | Sí | `OTP`, `TRANSACTIONAL`, `PROMOTIONAL` o `MULTI_USE` |
| `phoneNumbers`, `emails`, `websites` | Al menos un contacto | Lista con `value` y `label` |
| `privacy.uri`, `termsConditions.uri` | Sí | Enlaces de privacidad y términos |
| `brandContactName`, `brandContactEmailAddress`, `brandWebsiteUrl` | Sí | Contacto de la marca |
| `brazil.cnpj`, `brazil.legalName` | Sí (Brasil) | CNPJ de 14 dígitos y razón social |
| `brazil.brandAuthorizationAccepted` | Sí (Brasil) | Debe ser `true` |
| `launch.*` | Sí | Cuestionario de lanzamiento (disparador, interacciones, opt-out, instrucciones de acceso) |
## 3. Enviar a aprobación
```http theme={null}
POST /v1/rcs/instances/:instanceId/submit
Authorization: Bearer sk_live_xxxxx
```
Perfil incompleto devuelve **400** (`RCS_PROFILE_INCOMPLETE`). Si ya está activo, **409** (`RCS_ALREADY_ACTIVE`).
Respuesta con revisión manual:
```json theme={null}
{
"success": true,
"data": { "onboardingStatus": "SUBMITTED", "awaitingPartner": true },
"standby": true,
"message": "Agent submitted for manual review."
}
```
## 4. Enviar con la instancia
Cuando `status` y `onboardingStatus` sean **ACTIVE**:
```json theme={null}
{
"from": "inst_rcs_abc123",
"to": ["5511999999999"],
"type": "card",
"payload": {
"cardImage": "https://cdn.example.com/rcs/oferta.jpg",
"cardTitle": "Oferta de la marca",
"cardMessage": "Exclusivo para usted.",
"buttons": [{ "text": "Comprar", "url": "https://example.com/comprar" }]
}
}
```
Si se omite `from`, la plataforma usa la **instancia predeterminada** del workspace (si ACTIVE) o el remitente compartido.
`instanceId` en el cuerpo sigue funcionando como alias legado, pero prefiera **`from`** (id, nombre o slug de la instancia).
Instancia inactiva devuelve **503** (`RCS_INSTANCE_NOT_ACTIVE`). Instancia inexistente devuelve **404** (`RCS_INSTANCE_NOT_FOUND`).
## Restricción por API Key
Si la clave tiene `instanceIds` definido, solo accede y envía por las instancias listadas. Lista vacía = acceso a todas.
## Errores comunes
El `slug` ya existe en este workspace. Elija otro u omita para generar automáticamente.
Agente activo en revisión con la operadora. Las ediciones directas al perfil publicado requieren un nuevo ciclo de revisión vía `pendingAgentProfile`.
Ya hay una revisión en curso. Espere aprobación o rechazo antes de otro PATCH.
Límite de instancias del plan alcanzado. Actualice el plan o elimine instancias no usadas.
El agente aún no fue aprobado. Revise `onboardingStatus` y `awaitingPartner`.
## Próximos pasos
* [Quick Start](/es/rcs-api/como-funciona/quick-start): primer envío
* [Ámbitos de la API Key](/es/rcs-api/como-funciona/escopos-da-api-key): permisos de instancia
* Referencia de la API (pestaña RCS): endpoints de instancias con ejemplos