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:
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
textou 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.