Quick Start

Do zero ao primeiro RCS na fila em poucos passos. Comece com sk_test_... no Sandbox. Nem todo aparelho recebe RCS — tenha SMS como plano B.

Em poucas palavras

Envie RCS para um ou vários números em formato internacional (E.164, sem +)
Escolha o tipo: basic, card, carousel, file ou template
(Opcional) Informe from para enviar pelo agente branded
Consulte um envio pelo id retornado na resposta
Cancele só enquanto estiver QUEUED ou SCHEDULED

Cada mensagem RCS consome 140 créditos (BASIC) ou 200 créditos (CARD, CAROUSEL, FILE). Contexto: Introdução. Escopos: Escopos da API Key.

Antes de começar

Chave com rcs:send (e rcs:read / rcs:cancel se for consultar ou cancelar)
Números em E.164 (ex.: 5511999999999, sem +)
Autenticação: Authorization: Bearer sk_live_... ou x-api-key
Base URL: https://api.notifique.dev

1. Enviar RCS (texto)

to é sempre um array (até 500 destinatários). Uma mensagem é criada por número.

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

{
  "to": ["5511999999999"],
  "type": "basic",
  "payload": {
    "message": "Olá! Este é um RCS de teste com texto simples."
  }
}

Resposta esperada: 202

{
  "success": true,
  "data": {
    "status": "QUEUED",
    "count": 1,
    "messageIds": ["clrcs1..."]
  }
}

Use o primeiro id de messageIds para consultar ou cancelar. Escopo: rcs:send.

2. Outros tipos de envio

Na referência da API (aba RCS), abra Enviar RCS e escolha o exemplo no playground. Resumo:

CARD (um cartão)

{
  "to": ["5511999999999"],
  "type": "card",
  "payload": {
    "cardImage": "https://cdn.example.com/rcs/oferta.jpg",
    "cardTitle": "Oferta especial",
    "cardMessage": "Válida até domingo. Aproveite!",
    "buttons": [
      { "text": "Ver oferta", "url": "https://example.com/promo" },
      { "text": "Não tenho interesse" }
    ]
  }
}

Em CARD, use cardMessage para o texto. O campo message não é exibido ao destinatário.

CAROUSEL (três cards)

{
  "to": ["5511999999999"],
  "type": "carousel",
  "payload": {
    "cards": [
      {
        "cardImage": "https://cdn.example.com/rcs/card-1.jpg",
        "cardTitle": "Opção 1",
        "cardMessage": "Descrição do primeiro card.",
        "buttons": [{ "text": "Escolher 1" }]
      },
      {
        "cardImage": "https://cdn.example.com/rcs/card-2.jpg",
        "cardTitle": "Opção 2",
        "cardMessage": "Descrição do segundo card.",
        "buttons": [{ "text": "Escolher 2" }]
      },
      {
        "cardImage": "https://cdn.example.com/rcs/card-3.jpg",
        "cardTitle": "Opção 3",
        "cardMessage": "Descrição do terceiro card.",
        "buttons": [{ "text": "Escolher 3", "url": "https://example.com/opcao-3" }]
      }
    ]
  }
}

FILE (arquivo)

{
  "to": ["5511999999999"],
  "type": "file",
  "payload": {
    "message": "Segue o documento em anexo.",
    "file": "https://cdn.example.com/rcs/contrato.pdf",
    "fileName": "contrato.pdf"
  }
}

Template do workspace

{
  "to": ["5511999999999"],
  "type": "template",
  "payload": {
    "templateId": "ID_DO_TEMPLATE",
    "variables": { "nome": "Maria", "codigo": "482910" }
  }
}

Referência: template-api.

Com agente branded (`from`)

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

A instância precisa estar ACTIVE. Guia completo: Instâncias RCS. Use type em minúsculo: basic, card, carousel, file ou template. messageType é aceito como alias legado. Agendar: inclua "schedule": { "sendAt": "2026-12-31T14:00:00.000Z" } (depende do plano). Em options: priority, webhook (url + secret) só para esse envio, metadata.

3. Listar histórico

GET /v1/rcs/messages?page=1&limit=20
Authorization: Bearer sk_live_xxxxx

Filtros opcionais: status (vírgula), to, fromDate, toDate. Escopo: rcs:read.

4. Consultar status e conteúdo enviado

O POST de envio devolve só messageIds e status (202). Para ver o que foi enviado (payload, messageType, refer), consulte pelo id:

GET /v1/rcs/messages/:id
Authorization: Bearer sk_live_xxxxx

Resposta esperada: 200

{
  "success": true,
  "data": {
    "rcsId": "clrcs1...",
    "to": "5511999999999",
    "messageType": "CARD",
    "payload": {
      "message": "",
      "cardImage": "https://cdn.example.com/rcs/oferta.jpg",
      "cardTitle": "Oferta especial",
      "cardMessage": "Válida até domingo.",
      "buttons": [{ "text": "Ver oferta", "url": "https://example.com/promo" }]
    },
    "refer": "pedido-123",
    "status": "DELIVERED",
    "sentAt": "2025-02-20T14:00:05.000Z",
    "deliveredAt": "2025-02-20T14:00:30.000Z"
  }
}

A listagem (GET /v1/rcs/messages) também traz payload em cada item. Escopo: rcs:read.

5. Listar respostas recebidas

GET /v1/rcs/inbound?linked=true
Authorization: Bearer sk_live_xxxxx

Retorna MO vinculados a envios outbound (relatedRcsLogId). Detalhe: GET /v1/rcs/inbound/:id — o objeto relatedRcsLog traz o mesmo nível de detalhe de GET /v1/rcs/messages/:id (rcsId, messageType, payload, status e timestamps de entrega).

6. Cancelar

Só com status QUEUED ou SCHEDULED:

POST /v1/rcs/messages/:id/cancel
Authorization: Bearer sk_live_xxxxx

Se já estiver SENT ou DELIVERED, a API retorna 400. Créditos do agendamento voltam para o workspace quando aplicável. Escopo: rcs:cancel.

7. Evitar duplicata

Header Idempotency-Key no POST de envio. Repetições em até 24 h não criam dois envios iguais. Veja Segurança e confiabilidade.

8. Webhooks (opcional)

Configure rcs.sent, rcs.delivered, rcs.clicked, rcs.failed e rcs.cancelled para acompanhar sem polling. Guia: Eventos dos webhooks.

Próximos passos

Introdução: quando usar e tipos de mensagem
Instâncias RCS: agente branded
Escopos: permissões da chave
Eventos dos webhooks: status em tempo real
Respostas de erro: códigos HTTP e code

API RCS

Mensagens

Instâncias

Inbound

Em poucas palavras

Antes de começar

1. Enviar RCS (texto)

2. Outros tipos de envio

CARD (um cartão)

CAROUSEL (três cards)

FILE (arquivo)

Template do workspace

Com agente branded (`from`)

3. Listar histórico

4. Consultar status e conteúdo enviado

5. Listar respostas recebidas

6. Cancelar

7. Evitar duplicata

8. Webhooks (opcional)

Próximos passos

​Em poucas palavras

​Antes de começar

​1. Enviar RCS (texto)

​2. Outros tipos de envio

​CARD (um cartão)

​CAROUSEL (três cards)

​FILE (arquivo)

​Template do workspace

​Com agente branded (from)

​3. Listar histórico

​4. Consultar status e conteúdo enviado

​5. Listar respostas recebidas

​6. Cancelar

​7. Evitar duplicata

​8. Webhooks (opcional)

​Próximos passos

Em poucas palavras

Antes de começar

1. Enviar RCS (texto)

2. Outros tipos de envio

CARD (um cartão)

CAROUSEL (três cards)

FILE (arquivo)

Template do workspace

Com agente branded (`from`)

3. Listar histórico

4. Consultar status e conteúdo enviado

5. Listar respostas recebidas

6. Cancelar

7. Evitar duplicata

8. Webhooks (opcional)

Próximos passos