Instancias RCS

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

DRAFT — instancia creada; edite nombre, displayName y agentProfile libremente
SUBMITTED / VERIFICATION_PENDING / LAUNCH_PENDING — en espera de revisión (awaitingPartner: true, standby: true al enviar)
ACTIVE — agente aprobado; puede enviar con from
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

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

{
  "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

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:

{
  "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:

{
  "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

409 RCS_SLUG_TAKEN

El slug ya existe en este workspace. Elija otro u omita para generar automáticamente.

409 RCS_PROFILE_LOCKED

Agente activo en revisión con la operadora. Las ediciones directas al perfil publicado requieren un nuevo ciclo de revisión vía pendingAgentProfile.

409 RCS_REVISION_IN_PROGRESS

Ya hay una revisión en curso. Espere aprobación o rechazo antes de otro PATCH.

403 PLAN_LIMIT_INSTANCES

Límite de instancias del plan alcanzado. Actualice el plan o elimine instancias no usadas.

503 RCS_INSTANCE_NOT_ACTIVE

El agente aún no fue aprobado. Revise onboardingStatus y awaitingPartner.

Próximos pasos

Quick Start: primer envío
Ámbitos de la API Key: permisos de instancia
Referencia de la API (pestaña RCS): endpoints de instancias con ejemplos

API E-mail

E-mail

Domínios

E-mails recebidos

En pocas palabras

¿Cuándo crear una instancia?

Flujo de aprovisionamiento

1. Crear instancia

2. Completar el perfil del agente

3. Enviar a aprobación

4. Enviar con la instancia

Restricción por API Key

Errores comunes

Próximos pasos

​En pocas palabras

​¿Cuándo crear una instancia?

​Flujo de aprovisionamiento

​1. Crear instancia

​2. Completar el perfil del agente

​3. Enviar a aprobación

​4. Enviar con la instancia

​Restricción por API Key

​Errores comunes

​Próximos pasos

En pocas palabras

¿Cuándo crear una instancia?

Flujo de aprovisionamiento

1. Crear instancia

2. Completar el perfil del agente

3. Enviar a aprobación

4. Enviar con la instancia

Restricción por API Key

Errores comunes

Próximos pasos