Enviar RCS

A operação transaccional de RCS consiste no envio de uma mensagem RCS para um ou mais destinatários que não pertencem à audiência da organização. Como tal, não depende de um schema previamente definido para a audiência de contactos.

Existe um limite de 10 mensagens RCS por pedido HTTP à API Arpoone, configuradas através do campo messages.

Cada elemento do array messages representa uma mensagem RCS independente e pode especificar um destinatário, remetente, data de expiração e conteúdo diferentes.

Deve ser dada especial atenção ao campo to no payload transaccional de RCS. O número de telefone de destino deve ser um MSISDN válido e incluir o indicativo telefónico do país. Por exemplo, um MSISDN português deve começar por 351 (por exemplo, 351913462111).

Estrutura do pedido

{
  "organizationId": "<uuid>",
  "messages": [
    {
      "to": "<msisdn>",
      "from": "<string>",
      "expirationDateTime": "<dateTime>",
      "contentMessage": {
        "<contentType>": {}
      }
    }
  ]
}

A estrutura acima é uma representação simplificada do pedido. As propriedades aceites por contentMessage dependem do tipo de conteúdo RCS seleccionado.

Propriedades do pedido

Objecto raiz

Propriedade	Tipo	Obrigatório	Descrição
`organizationId`	UUID	Sim	Identificador único da Organização Arpoone onde a operação será realizada, uma vez que um utilizador pode ter acesso a mais do que uma Organização.
`messages`	Array	Sim	Colecção de mensagens RCS a enviar. O array deve conter entre 1 e 10 elementos.

Objecto de mensagem

Propriedade	Tipo	Obrigatório	Descrição
`to`	String	Sim	Número de telemóvel do destinatário, incluindo o indicativo telefónico do país.
`from`	String	Sim	Identificador do remetente ou agente RCS configurado para a organização.
`expirationDateTime`	DateTime	Não	Data e hora após as quais a mensagem já não deverá ser entregue. O valor deve utilizar o formato ISO 8601, incluindo o desvio UTC aplicável.
`contentMessage`	Object	Sim	Conteúdo RCS a enviar. O objecto deve conter um tipo de conteúdo primário suportado.

Regras de conteúdo

Cada mensagem deve conter um contentMessage.

Os tipos de conteúdo primário suportados são:

text
contentInfo
richCard

Apenas deve ser incluído um tipo de conteúdo primário no mesmo contentMessage. Por exemplo, uma mensagem não deve conter simultaneamente text e richCard.

A propriedade suggestions não é considerada um tipo de conteúdo primário e pode ser combinada com conteúdo de texto.

Exemplos

{
  "contentMessage": {
    "text": "Your order is ready."
  }
}

{
  "contentMessage": {
    "contentInfo": {
      "fileUrl": "https://cdn.example.com/order-confirmation.pdf",
      "mimeType": "application/pdf"
    }
  }
}

{
  "contentMessage": {
    "richCard": {
      "standaloneCard": {}
    }
  }
}

Limites do pedido

Limite	Valor
Máximo de mensagens por pedido HTTP	10
Tamanho máximo por mensagem	250 KB
Comprimento máximo de uma mensagem de texto	3 072 caracteres
Máximo de sugestões ao nível da mensagem	11
Máximo de sugestões por rich card	4
Máximo de cartões num carrossel	10
Mínimo de cartões num carrossel	2

O limite de 250 KB aplica-se individualmente a cada elemento do array messages e não ao pedido HTTP completo.

O envio em lote não combina os elementos numa única mensagem RCS. Cada mensagem é validada e processada de forma independente.

Mensagens de texto

Uma mensagem de texto é enviada através da propriedade text.

O comprimento máximo do texto é de 3 072 caracteres.

Exemplo de mensagem de texto

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345678",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "text": "Your order is ready for collection."
        }
      }
    ]
  }'

Mensagem de texto com respostas sugeridas

As mensagens de texto podem incluir respostas sugeridas e acções sugeridas através do array suggestions.

Uma mensagem pode conter até 11 sugestões ao nível da mensagem.

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345678",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "text": "Would you like to confirm your appointment?",
          "suggestions": [
            {
              "reply": {
                "text": "Confirm",
                "postbackData": "appointment-confirm"
              }
            },
            {
              "reply": {
                "text": "Reschedule",
                "postbackData": "appointment-reschedule"
              }
            }
          ]
        }
      }
    ]
  }'

Mensagens multimédia

Uma mensagem exclusivamente multimédia é enviada através de contentInfo.

A API Arpoone não aceita ficheiros multimédia como conteúdo Base64 nem como uploads de ficheiros multipart para esta operação. O ficheiro multimédia deve ser disponibilizado pelo cliente através de um URL antes do envio da mensagem.

Propriedades das informações de conteúdo

Propriedade	Tipo	Obrigatório	Descrição
`fileUrl`	String	Sim	URL HTTPS publicamente acessível através do qual o ficheiro multimédia pode ser obtido.
`thumbnailUrl`	String	Não	URL HTTPS publicamente acessível da miniatura associada ao ficheiro multimédia. Comprimento máximo: 2 048 caracteres.
`mimeType`	String	Sim	Tipo MIME do recurso multimédia. O valor deve corresponder a um dos tipos de multimédia suportados.

Requisitos do URL de multimédia

Para conteúdo multimédia referenciado por URL, a Arpoone exige as seguintes condições para garantir que o ficheiro pode ser obtido e processado de forma fiável:

utilizar HTTPS;
estar acessível externamente através de um pedido HTTP GET;
devolver directamente o conteúdo multimédia;
não exigir uma sessão de utilizador autenticada;
permanecer acessível durante o processamento e a entrega da mensagem;
devolver conteúdo consistente com o mimeType declarado.

O cliente é responsável pelo alojamento do ficheiro e por assegurar a sua disponibilidade contínua.

Tipos de multimédia suportados

Imagens

image/jpeg
image/jpg
image/gif
image/png

Vídeo

video/h263
video/m4v
video/mp4
video/mpeg
video/mpeg4
video/webm

Documentos

application/pdf

Estes são os tipos de multimédia actualmente identificados como suportados pela integração Arpoone.

A Google indica que o suporte de PDF em rich cards pode depender da geografia e do cliente de mensagens do destinatário. Especificamente, a documentação actual de rich cards indica que as rich cards com PDF estão disponíveis apenas na Índia, no cliente Google Messages.

Exemplo de mensagem multimédia

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345678",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "contentInfo": {
            "fileUrl": "https://cdn.example.com/media/product.jpg",
            "thumbnailUrl": "https://cdn.example.com/media/product-thumbnail.jpg",
            "mimeType": "image/jpeg"
          }
        }
      }
    ]
  }'

Rich cards

As rich cards podem combinar conteúdo multimédia, um título, uma descrição e sugestões numa única mensagem.

A API suporta:

rich cards autónomas;
carrosséis de rich cards.

As rich cards podem combinar conteúdo multimédia, texto de título, texto de descrição, respostas sugeridas e acções sugeridas. O suporte e a apresentação podem variar consoante as capacidades do dispositivo do destinatário.

Propriedades do conteúdo do cartão

Uma rich card deve conter conteúdo significativo. Deve ser fornecido, pelo menos, um title, description ou media.

O material de integração especifica ainda que, quando um cartão horizontal contém conteúdo multimédia, deve também incluir, pelo menos, um title, description ou suggestion.

Propriedade	Tipo	Obrigatório	Descrição
`title`	String	Condicional	Título da rich card. Comprimento máximo: 200 caracteres.
`description`	String	Condicional	Descrição da rich card. Comprimento máximo: 2 000 caracteres.
`media`	Object	Condicional	Conteúdo multimédia apresentado na rich card. Segue as mesmas restrições de multimédia aplicáveis a uma mensagem exclusivamente multimédia.
`suggestions`	Array	Não	Respostas ou acções sugeridas associadas ao cartão. Máximo: 4 elementos por cartão.

Rich card autónoma

Propriedades do cartão autónomo

Propriedade	Tipo	Obrigatório	Descrição
`cardOrientation`	Enum	Sim	Orientação do cartão. Valores aceites: `VERTICAL` ou `HORIZONTAL`.
`thumbnailImageAlignment`	Enum	Condicional	Alinhamento da miniatura num cartão horizontal. Valores aceites: `LEFT` ou `RIGHT`.
`cardContent`	Object	Sim	Conteúdo apresentado no cartão.

Propriedades de multimédia numa rich card

Propriedade	Tipo	Obrigatório	Descrição
`height`	Enum	Não	Altura da pré-visualização do conteúdo multimédia. Valores aceites: `SHORT`, `MEDIUM` ou `TALL`.
`contentInfo`	Object	Sim	URL do conteúdo multimédia, URL opcional da miniatura e tipo MIME.

A API define as seguintes alturas de pré-visualização de multimédia: 112 DP para SHORT, 168 DP para MEDIUM e 264 DP para TALL. Se as dimensões do conteúdo multimédia não corresponderem à altura seleccionada, a imagem poderá ser ampliada e recortada ao centro.

Exemplo de rich card autónoma

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345678",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "richCard": {
            "standaloneCard": {
              "cardOrientation": "VERTICAL",
              "thumbnailImageAlignment": "LEFT",
              "cardContent": {
                "title": "New product available",
                "description": "Discover the latest product in our catalogue.",
                "media": {
                  "height": "MEDIUM",
                  "contentInfo": {
                    "fileUrl": "https://cdn.example.com/media/product.jpg",
                    "thumbnailUrl": "https://cdn.example.com/media/product-thumbnail.jpg",
                    "mimeType": "image/jpeg"
                  }
                },
                "suggestions": [
                  {
                    "openUrlAction": {
                      "text": "View product",
                      "url": "https://www.example.com/products/123",
                      "postbackData": "view-product-123"
                    }
                  }
                ]
              }
            }
          }
        }
      }
    ]
  }'

Carrossel de rich cards

Um carrossel contém entre 2 e 10 cartões.

Cada elemento de cardContents segue as regras de conteúdo das rich cards, incluindo um máximo de quatro sugestões por cartão.

Propriedades do carrossel

Propriedade	Tipo	Obrigatório	Descrição
`cardWidth`	Enum	Sim	Largura aplicada aos cartões do carrossel. Valores aceites: `SMALL` ou `MEDIUM`.
`cardContents`	Array	Sim	Cartões apresentados no carrossel. O array deve conter entre 2 e 10 elementos.

Exemplo de carrossel

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345678",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "richCard": {
            "carouselCard": {
              "cardWidth": "MEDIUM",
              "cardContents": [
                {
                  "title": "Product A",
                  "description": "Description of product A.",
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://cdn.example.com/media/product-a.jpg",
                      "mimeType": "image/jpeg"
                    }
                  },
                  "suggestions": [{"reply": {"text": "Select A", "postbackData": "select-product-a"}}]
                },
                {
                  "title": "Product B",
                  "description": "Description of product B.",
                  "media": {
                    "height": "MEDIUM",
                    "contentInfo": {
                      "fileUrl": "https://cdn.example.com/media/product-b.jpg",
                      "mimeType": "image/jpeg"
                    }
                  },
                  "suggestions": [{"reply": {"text": "Select B", "postbackData": "select-product-b"}}]
                }
              ]
            }
          }
        }
      }
    ]
  }'

Sugestões

As sugestões permitem ao destinatário responder ou executar uma acção predefinida directamente a partir da conversa RCS.

São suportados os seguintes tipos de sugestão:

resposta sugerida;
abrir um URL;
marcar um número de telefone;
ver uma localização;
partilhar a localização do destinatário;
criar um evento de calendário.

Cada elemento do array suggestions deve conter exactamente um tipo de sugestão.

Limites comuns das sugestões

Estes limites aplicam-se a todos os tipos de sugestão RCS suportados.

Propriedade	Comprimento máximo
Texto da sugestão	25 caracteres
`postbackData`	2 000 caracteres
URL a abrir	2 048 caracteres

Resposta sugerida

Uma resposta sugerida apresenta ao destinatário uma resposta predefinida.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão e devolvido como resposta sugerida. Máximo: 25 caracteres.
`postbackData`	String	Sim	Dados devolvidos ao cliente quando o destinatário selecciona a sugestão. Máximo: 2 000 caracteres.

{
  "reply": {
    "text": "Confirm",
    "postbackData": "confirm-order"
  }
}

Acção de abertura de URL

Abre um URL quando seleccionado pelo destinatário.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão. Máximo: 25 caracteres.
`url`	String	Sim	URL a abrir. Máximo: 2 048 caracteres.
`postbackData`	String	Sim	Dados associados à acção. Máximo: 2 000 caracteres.

{
  "openUrlAction": {
    "text": "View details",
    "url": "https://www.example.com/orders/123",
    "postbackData": "view-order-123"
  }
}

Acção de chamada

Inicia uma chamada telefónica para o número especificado.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão. Máximo: 25 caracteres.
`phoneNumber`	String	Sim	Número de telefone no formato E.164, por exemplo, `+351211234567`.
`postbackData`	String	Sim	Dados associados à acção. Máximo: 2 000 caracteres.

{
  "dialAction": {
    "text": "Call us",
    "phoneNumber": "+351211234567",
    "postbackData": "call-customer-service"
  }
}

Acção de visualização de localização

Apresenta uma localização geográfica especificada.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão. Máximo: 25 caracteres.
`latitude`	Decimal	Sim	Latitude no intervalo de -90 a 90.
`longitude`	Decimal	Sim	Longitude no intervalo de -180 a 180.
`label`	String	Não	Descrição ou etiqueta associada à localização. Máximo: 100 caracteres.
`postbackData`	String	Sim	Dados associados à acção. Máximo: 2 000 caracteres.

{
  "viewLocationAction": {
    "text": "View location",
    "latitude": 38.7223,
    "longitude": -9.1393,
    "label": "Lisbon office",
    "postbackData": "view-lisbon-office"
  }
}

O conteúdo de localização é suportado como acção de sugestão. Actualmente, o conteúdo de localização não é suportado como conteúdo principal de uma rich card. Em alternativa, pode ser referenciada uma imagem estática de mapa através do URL de multimédia da rich card.

Acção de partilha de localização

Solicita ao destinatário que partilhe a sua localização actual.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão. Máximo: 25 caracteres.
`postbackData`	String	Sim	Dados associados à acção. Máximo: 2 000 caracteres.

{
  "shareLocationAction": {
    "text": "Share location",
    "postbackData": "share-current-location"
  }
}

Acção de criação de evento de calendário

Permite ao destinatário criar um evento de calendário.

Propriedade	Tipo	Obrigatório	Descrição
`text`	String	Sim	Texto apresentado na sugestão. Máximo: 25 caracteres.
`title`	String	Sim	Título do evento de calendário. Máximo: 100 caracteres.
`description`	String	Não	Descrição do evento de calendário. Máximo: 500 caracteres.
`startTime`	DateTime	Sim	Data e hora de início do evento no formato ISO 8601.
`endTime`	DateTime	Sim	Data e hora de fim do evento no formato ISO 8601. Deve ser posterior a `startTime`.
`postbackData`	String	Sim	Dados associados à acção. Máximo: 2 000 caracteres.

{
  "createCalendarEventAction": {
    "text": "Add to calendar",
    "title": "Product demonstration",
    "description": "Online demonstration of the new product.",
    "startTime": "2026-09-10T09:00:00Z",
    "endTime": "2026-09-10T09:30:00Z",
    "postbackData": "calendar-product-demo"
  }
}

Exemplo de pedido em lote

O exemplo seguinte envia três mensagens RCS independentes através de um único pedido HTTP.

curl --location 'https://api.arpoone.com/v1.2/rcs/send' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <YOUR_API_KEY>' \
  --data '{
    "organizationId": "7bc05553-4b68-44e8-b7bc-37be63c6d9e9",
    "messages": [
      {
        "to": "351912345671",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {"text": "Your order has been shipped."}
      },
      {
        "to": "351912345672",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "text": "Your appointment is confirmed.",
          "suggestions": [{"reply": {"text": "Confirm", "postbackData": "appointment-confirm"}}]
        }
      },
      {
        "to": "351912345673",
        "from": "MyBrand",
        "expirationDateTime": "2026-09-02T16:00:00Z",
        "contentMessage": {
          "contentInfo": {
            "fileUrl": "https://cdn.example.com/documents/invoice.pdf",
            "mimeType": "application/pdf"
          }
        }
      }
    ]
  }'

Comportamento de processamento

O envio do pedido não significa necessariamente que as mensagens já tenham sido entregues aos respectivos destinatários.

Quando um pedido é aceite:

o pedido é autenticado;
a organização e o respectivo acesso ao canal RCS são validados;
cada mensagem e o respectivo conteúdo são validados;
o saldo RCS disponível é validado;
as mensagens aceites são submetidas para processamento assíncrono.

A entrega final pode depender de factores externos à API Arpoone, incluindo:

se o destinatário está acessível através de RCS;
se a rede do destinatário suporta o agente RCS;
as capacidades RCS suportadas pelo dispositivo do destinatário;
a validade e disponibilidade do conteúdo multimédia referenciado;
o processamento dos fornecedores e operadores a jusante.

Respostas HTTP

A operação segue o formato de resposta normalizado da API transaccional Arpoone.

Estado HTTP	Resultado
200 OK ou 202 Accepted	O pedido foi aceite para processamento.
400 Bad Request	O pedido contém dados ou conteúdo inválidos.
401 Unauthorized	A autenticação está em falta ou é inválida.
403 Forbidden	O utilizador autenticado ou a organização não está autorizado a utilizar a operação.
404 Not Found	Não foi encontrada uma organização referenciada ou outro recurso necessário.
402 Payment Required ou estado de saldo existente	A organização não dispõe de saldo RCS suficiente.
429 Too Many Requests	O limite aplicável à taxa de pedidos foi excedido.
500 Internal Server Error	Ocorreu um erro inesperado durante o processamento do pedido.
503 Service Unavailable	O serviço encontra-se temporariamente indisponível.

Erros

Em situações de erro, a propriedade error na resposta será populada com um objeto que contém informações sobre o erro ocorrido:

{
  "error": {
    "code": "MESSAGES_EMPTY",
    "param": "",
    "description": "MESSAGES_EMPTY"
  },
  "messages": null
}

A propriedade code especifica que tipo de erro ocorreu sendo que a propriedade param especifica qual o parâmetro do payload de envio de RCS que causou o erro.

A lista completa de códigos de erro pode ser consultada neste link

Aceder à API Reference

Enviar RCS

Estrutura do pedido​

Propriedades do pedido​

Objecto raiz​

Objecto de mensagem​

Regras de conteúdo​

Exemplos​

Limites do pedido​

Mensagens de texto​

Exemplo de mensagem de texto​

Mensagem de texto com respostas sugeridas​

Mensagens multimédia​

Propriedades das informações de conteúdo​

Requisitos do URL de multimédia​

Tipos de multimédia suportados​

Imagens​

Vídeo​

Documentos​

Exemplo de mensagem multimédia​

Rich cards​

Propriedades do conteúdo do cartão​

Rich card autónoma​

Propriedades do cartão autónomo​

Propriedades de multimédia numa rich card​

Exemplo de rich card autónoma​

Carrossel de rich cards​

Propriedades do carrossel​

Exemplo de carrossel​

Sugestões​

Limites comuns das sugestões​

Resposta sugerida​

Acção de abertura de URL​

Acção de chamada​

Acção de visualização de localização​

Acção de partilha de localização​

Acção de criação de evento de calendário​

Exemplo de pedido em lote​

Comportamento de processamento​

Respostas HTTP​

Erros​