StatusDesenvolvedoresParceirosPTENESEntrar
Falar com vendasCriar conta grátis
Criar conta grátis
Falar com vendasCriar conta grátis
EntrarStatusPTENES

Referência da API

RCS

Envie mensagens RCS com fallback para SMS, liste os envios do ambiente da sua chave e consulte por qual canal cada mensagem de fato saiu para o aparelho.

  • 3 operações
  • URL basehttps://api.messages.ccxcompany.co
  • AutenticaçãoBearer com a sua chave de API

O texto técnico abaixo vem do contrato público, o openapi.json, no idioma em que o contrato foi escrito.

Lista mensagens RCS

GET/v2/rcs/messages

As mensagens da sua organização, mais recentes primeiro. O ambiente vem da credencial: uma chave de sandbox lista só o que saiu no sandbox.

Permissão: rcs:read.

Parâmetros

CampoOndeTipoDescrição
statusopcionalquerystringValores:queuedsentdeliveredreadfailed
channelopcionalquerystringValores:rcssms
campaignIdopcionalquerystring
limitopcionalqueryinteger

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    itemsobrigatórioobject[]
    items[].idobrigatóriostring
    items[].toobrigatóriostring
    items[].contentobrigatórioobject
    items[].content.textopcionalstring
    items[].content.cardopcionalobject
    items[].routeobrigatóriostringValores:easy_rcseasy_otp_rcs
    items[].statusobrigatóriostringValores:queuedsentdeliveredreadfailed
    items[].channelopcionalstringValores:rcssms
    items[].envobrigatóriostringValores:livetest
    items[].contactIdopcionalstring
    items[].campaignIdopcionalstring
    items[].metadataopcionalobjectMetadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
    items[].failureReasonopcionalstring
    items[].sentAtopcionalstring · date-time
    items[].deliveredAtopcionalstring · date-time
    items[].readAtopcionalstring · date-time
    items[].createdAtobrigatóriostring · date-time
    nextCursoropcionalstring
    JSON
    {  "items": [    {      "id": "string",      "to": "string",      "content": {        "text": "string"      },      "route": "easy_rcs",      "status": "queued",      "channel": "rcs",      "env": "live",      "contactId": "string",      "campaignId": "string",      "metadata": {},      "failureReason": "string",      "sentAt": "2026-10-16T12:00:00.000Z",      "deliveredAt": "2026-10-16T12:00:00.000Z",      "readAt": "2026-10-16T12:00:00.000Z",      "createdAt": "2026-10-16T12:00:00.000Z"    }  ],  "nextCursor": "string"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/v2/rcs/messages' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Envia uma mensagem RCS

POST/v2/rcs/messages

Envio síncrono: a resposta chega depois de o provedor aceitar (ou recusar). A entrega é assíncrona e chega no seu webhook como rcs.delivered, rcs.read ou rcs.failed (com data.channel dizendo se saiu por RCS ou pelo fallback de SMS).

`Idempotency-Key` é obrigatória. Repetir a chave com o mesmo corpo devolve a resposta original e não envia nada; corpo diferente é 409.

Conteúdo — dois formatos, e o campo escolhe a rota interna:

contentvira
{ "text": "…" }mensagem simples, até 160 caracteres
{ "card": { … } }cartão com título, descrição, imagem e até 4 botões

Botões (suggestions) aceitam openUrl, call e reply. fileUrl precisa ser HTTPS em domínio público — o aparelho baixa a mídia direto.

Fallback para SMS — o RCS não chega em todo aparelho. Quando você declara fallback, quem não tem RCS recebe um SMS com aquele texto; sem `fallback`, essa pessoa não recebe nada. O texto do fallback é limitado a 160 caracteres sem acentos: acento leva o SMS para UCS-2 e muda o que ele custa.

Canal do desfecho: a resposta traz channel só depois que o provedor informa por onde a mensagem saiu (rcs ou sms). No aceite ele vem ausente — e ausente significa "ainda não se sabe", nunca "foi por RCS".

Ambiente: vem da credencial, nunca do corpo.

Preço: cobrado por MENSAGEM (não por segmento, como o SMS): um cartão longo custa o mesmo que um texto curto. Rotas: easy_rcs e easy_otp_rcs (Cl. 8.7). Saldo insuficiente é 402.

Opt-out: na rota easy_rcs, destinatário cujo contato pediu para não receber comunicação é recusado com 422 e meta.motivo: "opt_out". easy_otp_rcs é transacional e sai sempre.

Permissão: rcs:send.

Corpo da requisiçãoapplication/json

CampoTipoDescrição
toobrigatóriostring
contentobrigatórioobjectConteúdo: {text} para mensagem simples (até 160) ou {card} para cartão com imagem e até 4 botões.
content.textopcionalstring
content.cardopcionalobject
content.card.titleobrigatóriostring
content.card.descriptionobrigatóriostring
content.card.fileUrlopcionalstring · uri
content.card.suggestionsopcionalobject[]
routeobrigatóriostringRota tarifária (obrigatória): easy_rcs | easy_otp_rcs.Valores:easy_rcseasy_otp_rcs
fallbackopcionalobjectTexto enviado por SMS quando o aparelho não suporta RCS. Sem ele, o destinatário sem RCS não recebe nada.
fallback.textobrigatóriostring
contactIdopcionalstring
campaignIdopcionalstring
metadataopcionalobjectMetadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
trackLinksopcionalbooleantrue troca as URLs do texto e dos botões openUrl por links curtos e publica rcs.clicked a cada clique. fileUrl não é trocada.
Exemplo completo do corpo
JSON
{  "to": "string",  "content": {    "text": "string"  },  "route": "easy_rcs",  "fallback": {    "text": "string"  },  "contactId": "string",  "campaignId": "string",  "metadata": {},  "trackLinks": true}

Respostas

  • 201Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostring
    toobrigatóriostring
    contentobrigatórioobject
    content.textopcionalstring
    content.cardopcionalobject
    content.card.titleobrigatóriostring
    content.card.descriptionobrigatóriostring
    content.card.fileUrlopcionalstring · uri
    content.card.suggestionsopcionalobject[]
    routeobrigatóriostringValores:easy_rcseasy_otp_rcs
    statusobrigatóriostringValores:queuedsentdeliveredreadfailed
    channelopcionalstringValores:rcssms
    envobrigatóriostringValores:livetest
    contactIdopcionalstring
    campaignIdopcionalstring
    metadataopcionalobjectMetadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
    failureReasonopcionalstring
    sentAtopcionalstring · date-time
    deliveredAtopcionalstring · date-time
    readAtopcionalstring · date-time
    createdAtobrigatóriostring · date-time
    JSON
    {  "id": "string",  "to": "string",  "content": {    "text": "string"  },  "route": "easy_rcs",  "status": "queued",  "channel": "rcs",  "env": "live",  "contactId": "string",  "campaignId": "string",  "metadata": {},  "failureReason": "string",  "sentAt": "2026-10-16T12:00:00.000Z",  "deliveredAt": "2026-10-16T12:00:00.000Z",  "readAt": "2026-10-16T12:00:00.000Z",  "createdAt": "2026-10-16T12:00:00.000Z"}

  • 400RFC 7807 problem details for BAD_REQUEST (400).

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 402RFC 7807 problem details for PAYMENT_REQUIRED (402).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 409RFC 7807 problem details for CONFLICT (409).

  • 412RFC 7807 problem details for PRECONDITION_FAILED (412).

  • 422RFC 7807 problem details for VALIDATION_ERROR (422).

  • 502RFC 7807 problem details for DEPENDENCY_FAILED (502).

  • 503RFC 7807 problem details for SERVICE_UNAVAILABLE (503).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl -X POST 'https://api.messages.ccxcompany.co/v2/rcs/messages' \  -H "Authorization: Bearer $CCX_API_KEY" \  -H "Idempotency-Key: order-4821" \  -H "Content-Type: application/json" \  -d '{    "to": "string",    "content": {      "text": "string"    },    "route": "easy_rcs"  }'
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Consulta uma mensagem RCS

GET/v2/rcs/messages/{id}

O estado atual de um envio, incluindo o channel por onde ele de fato saiu quando o provedor já informou.

Permissão: rcs:read.

Parâmetros

CampoOndeTipoDescrição
idobrigatóriocaminhostring

Respostas

  • 200Default Response

    Campos e exemplo da resposta
    CampoTipoDescrição
    idobrigatóriostring
    toobrigatóriostring
    contentobrigatórioobject
    content.textopcionalstring
    content.cardopcionalobject
    content.card.titleobrigatóriostring
    content.card.descriptionobrigatóriostring
    content.card.fileUrlopcionalstring · uri
    content.card.suggestionsopcionalobject[]
    routeobrigatóriostringValores:easy_rcseasy_otp_rcs
    statusobrigatóriostringValores:queuedsentdeliveredreadfailed
    channelopcionalstringValores:rcssms
    envobrigatóriostringValores:livetest
    contactIdopcionalstring
    campaignIdopcionalstring
    metadataopcionalobjectMetadados de correlação do seu sistema (ex.: customerId, journeyId), devolvidos intactos em todo webhook desta mensagem. Até 20 chaves; chave começa por letra e usa [A-Za-z0-9_.-] (até 64); valor é texto (até 256), número ou booleano. Não envie dado pessoal aqui.
    failureReasonopcionalstring
    sentAtopcionalstring · date-time
    deliveredAtopcionalstring · date-time
    readAtopcionalstring · date-time
    createdAtobrigatóriostring · date-time
    JSON
    {  "id": "string",  "to": "string",  "content": {    "text": "string"  },  "route": "easy_rcs",  "status": "queued",  "channel": "rcs",  "env": "live",  "contactId": "string",  "campaignId": "string",  "metadata": {},  "failureReason": "string",  "sentAt": "2026-10-16T12:00:00.000Z",  "deliveredAt": "2026-10-16T12:00:00.000Z",  "readAt": "2026-10-16T12:00:00.000Z",  "createdAt": "2026-10-16T12:00:00.000Z"}

  • 401RFC 7807 problem details for UNAUTHORIZED (401).

  • 403RFC 7807 problem details for FORBIDDEN (403).

  • 404RFC 7807 problem details for NOT_FOUND (404).

As respostas de erro seguem o formato RFC 7807 (application/problem+json), com um código estável no campo code. Ver os códigos de erro

Exemplo em curl

cURL
curl 'https://api.messages.ccxcompany.co/v2/rcs/messages/<id>' \  -H "Authorization: Bearer $CCX_API_KEY"
Só os campos obrigatórios. Troque os valores de exemplo pelos seus.

Outras áreas da API

Travou em alguma rota? Fale com quem mantém a API.

Criar conta grátisFalar com vendas

Criando a conta pelo site, você ganha R$ 10 de crédito de teste.