Instâncias RCS

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

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

DRAFT — instância criada; edite nome, displayName e agentProfile livremente
SUBMITTED / VERIFICATION_PENDING / LAUNCH_PENDING — aguardando revisão (awaitingPartner: true, standby: true na submissão)
ACTIVE — agente aprovado; pode enviar com from
REJECTED — corrija o perfil e submeta de novo

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.

1. Criar instância

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

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

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

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:

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

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

instanceId no corpo ainda funciona como alias legado, mas prefira from (id, nome da instância ou slug).

Instância inativa retorna 503 (RCS_INSTANCE_NOT_ACTIVE). Instância inexistente retorna 404 (RCS_INSTANCE_NOT_FOUND).

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

409 RCS_SLUG_TAKEN

O slug já existe neste workspace. Escolha outro ou omita para gerar automaticamente.

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.

409 RCS_REVISION_IN_PROGRESS

Já há uma revisão em andamento. Aguarde aprovação ou rejeição antes de novo PATCH.

403 PLAN_LIMIT_INSTANCES

Limite de instâncias do plano atingido. Faça upgrade ou remova instâncias não usadas.

503 RCS_INSTANCE_NOT_ACTIVE

O agente ainda não foi aprovado. Confira onboardingStatus e awaitingPartner.

Próximos passos

Quick Start: primeiro envio
Escopos da API Key: permissões de instância
Referência da API (aba RCS): endpoints de instâncias com exemplos

API RCS

Mensagens

Instâncias

Inbound

Em poucas palavras

Quando criar uma instância?

Fluxo de provisionamento

1. Criar instância

2. Preencher o perfil do agente

3. Submeter para aprovação

4. Enviar com a instância

Restrição por API Key

Erros comuns

Próximos passos

​Em poucas palavras

​Quando criar uma instância?

​Fluxo de provisionamento

​1. Criar instância

​2. Preencher o perfil do agente

​3. Submeter para aprovação

​4. Enviar com a instância

​Restrição por API Key

​Erros comuns

​Próximos passos

Em poucas palavras

Quando criar uma instância?

Fluxo de provisionamento

1. Criar instância

2. Preencher o perfil do agente

3. Submeter para aprovação

4. Enviar com a instância

Restrição por API Key

Erros comuns

Próximos passos