Pular para conteúdo

Enviar mensagens

Todas as mensagens usam POST /rcs, com a mesma chave de API do SMS. Cada envio leva exatamente um destes conteúdos: text, card, carousel ou media_url.

Texto

curl https://sms.example.com/api/v1/rcs \
  -H "Authorization: Bearer $CHAVE" \
  -H "Content-Type: application/json" \
  -d '{"to": "5511999990000", "text": "Seu pedido 4821 saiu para entrega."}'

Até 160 caracteres e sem botões, o envio é cobrado como basic. O texto aceita até 3072 caracteres.

Cartão

Imagem, título, descrição e até 4 botões em um bloco só.

{
  "to": "5511999990000",
  "card": {
    "title": "Consulta amanhã às 14h",
    "description": "Confirme sua presença",
    "media_url": "https://exemplo.com/clinica.jpg",
    "media_height": "medium",
    "suggestions": [
      { "type": "reply", "text": "Confirmar", "postback": "confirmar_123" },
      { "type": "reply", "text": "Remarcar", "postback": "remarcar_123" },
      { "type": "url", "text": "Como chegar", "url": "https://maps.google.com/?q=clinica" }
    ]
  },
  "fallback_text": "Consulta amanhã às 14h. Responda SIM para confirmar."
}
Campo Limite
title 200 caracteres
description 2000 caracteres
media_url URL pública de imagem ou vídeo
media_height short, medium ou tall
suggestions Até 4 botões

O cartão precisa ter pelo menos um entre title, description e media_url.

Carrossel

De 2 a 10 cartões lado a lado, que o cliente desliza.

{
  "to": "5511999990000",
  "carousel": {
    "width": "medium",
    "cards": [
      { "title": "Plano 300 Mega", "description": "R$ 99,90/mês", "media_url": "https://exemplo.com/300.jpg",
        "suggestions": [{ "type": "reply", "text": "Quero este", "postback": "plano_300" }] },
      { "title": "Plano 600 Mega", "description": "R$ 129,90/mês", "media_url": "https://exemplo.com/600.jpg",
        "suggestions": [{ "type": "reply", "text": "Quero este", "postback": "plano_600" }] }
    ]
  }
}

width pode ser small ou medium (padrão).

Mídia

Uma imagem, vídeo ou arquivo sozinho:

{ "to": "5511999990000", "media_url": "https://exemplo.com/fatura-outubro.pdf" }

Botões

Há três tipos. O texto de cada botão tem até 25 caracteres.

type Campos O que acontece no toque
reply text, postback (até 120 caracteres) O cliente responde; você recebe o postback no evento rcs.received
url text, url Abre o endereço no navegador
dial text, phone Abre o discador com o número

Botões dentro de um cartão vão em card.suggestions (até 4). Botões soltos embaixo da mensagem vão em suggestions no nível principal (até 11).

Troca para SMS

Por padrão (fallback: true), se o aparelho não tiver RCS ou a entrega falhar, a plataforma envia um SMS:

  • com o texto de fallback_text, se informado;
  • senão, com o text ou com o título e a descrição do cartão.

Quando a troca acontece no próprio envio, a resposta vem com status: "fallback_sms" e um objeto sms com o id do SMS. Se acontecer depois, você recebe o evento rcs.status com fallback_sms.

Escreva sempre o fallback_text

Carrosséis e cartões com botões não cabem bem em SMS. Um fallback_text curto, com a ação por escrito ("Responda SIM para confirmar"), garante que a mensagem faça sentido em qualquer aparelho.

Para nunca enviar SMS, use "fallback": false: a mensagem fica como failed e o valor do RCS é devolvido.

Resposta

{
  "id": "5f0c2b1e-9a7d-4c1e-8f43-2b6a1d0e7c55",
  "to": "5511999990000",
  "status": "sent",
  "type": "rich",
  "price": 0.18,
  "currency": "BRL"
}

Guarde o id para consultar com GET /rcs/{id} e para relacionar os eventos. O campo opcional reference aceita o seu próprio identificador (até 64 caracteres), devolvido na consulta.