Send RCS

The transactional RCS operation consists of sending an RCS message to one or more recipients who do not belong to the organization’s audience. As such, it does not depend on a schema previously defined for the audience of contacts.

There is a limit of 10 RCS messages per HTTP request to the Arpoone API, configured through the messages field.

Each element of the messages array represents an independent RCS message and may specify a different recipient, sender, expiration date and content.

Special attention must be given to the to field in the transactional RCS payload. The destination phone number must be a valid MSISDN and include the country calling code. For example, a Portuguese MSISDN must start with 351 (e.g. 351913462111).

Request structure

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

The structure above is a simplified representation of the request. The properties accepted by contentMessage depend on the selected RCS content type.

Request properties

Root object

Property	Type	Required	Description
`organizationId`	UUID	Yes	Unique identifier of the Arpoone Organization where the operation will take place, as a user may have access to more than one Organization.
`messages`	Array	Yes	Collection of RCS messages to send. The array must contain between 1 and 10 elements.

Message object

Property	Type	Required	Description
`to`	String	Yes	Recipient's mobile number, including the country calling code.
`from`	String	Yes	RCS sender or agent identifier configured for the organization.
`expirationDateTime`	DateTime	No	Date and time after which the message must no longer be delivered. The value must use ISO 8601 format, including the applicable UTC offset.
`contentMessage`	Object	Yes	RCS content to send. The object must contain one supported primary content type.

Content rules

Each message must contain one contentMessage.

The supported primary content types are:

text
contentInfo
richCard

Only one primary content type should be included in the same contentMessage. For example, a message must not contain both text and richCard.

The suggestions property is not considered a primary content type and can be combined with text content.

Examples

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

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

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

Request limits

Limit	Value
Maximum messages per HTTP request	10
Maximum size per message	250 KB
Maximum text message length	3,072 characters
Maximum message-level suggestions	11
Maximum suggestions per rich card	4
Maximum cards in a carousel	10
Minimum cards in a carousel	2

The 250 KB limit applies individually to each element of the messages array and not to the complete HTTP request.

Batch submission does not combine the elements into a single RCS message. Each message is validated and processed independently.

Text messages

A text message is sent using the text property.

The maximum text length is 3,072 characters.

Text message example

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."
        }
      }
    ]
  }'

Text message with suggested replies

Text messages can include suggested replies and suggested actions through the suggestions array.

A message can contain up to 11 message-level suggestions.

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

Media messages

A media-only message is sent using contentInfo.

The Arpoone API does not accept media files as Base64 content or as multipart file uploads for this operation. The media file must be made available by the client through a URL before submitting the message.

Content information properties

Property	Type	Required	Description
`fileUrl`	String	Yes	Publicly accessible HTTPS URL from which the media file can be retrieved.
`thumbnailUrl`	String	No	Publicly accessible HTTPS URL of the thumbnail associated with the media file. Maximum length: 2,048 characters.
`mimeType`	String	Yes	MIME type of the media resource. The value must correspond to one of the supported media types.

Media URL requirements

For media referenced by URL, Arpoone requires the following conditions to ensure that the file can be retrieved and processed reliably:

use HTTPS;
be externally accessible through an HTTP GET request;
return the media content directly;
not require an authenticated user session;
remain accessible while the message is being processed and delivered;
return content consistent with the declared mimeType.

The client is responsible for hosting the file and ensuring its continued availability.

Supported media types

Images

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

Video

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

Documents

application/pdf

These are the media types currently identified as supported by the Arpoone integration.

Google notes that PDF support in rich cards may depend on geography and the recipient's messaging client. Specifically, its current rich-card documentation states that PDF rich cards are only available in India on the Google Messages client.

Media message example

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

Rich cards can combine media, a title, a description and suggestions in a single message.

The API supports:

standalone rich cards;
rich card carousels.

Rich cards can combine media, title text, description text, suggested replies and suggested actions. Support and rendering may vary depending on the capabilities of the recipient’s device.

Card content properties

A rich card must contain meaningful card content. At least one title, description or media should be provided.

The integration material additionally specifies that when a horizontal card contains media, it must also include at least a title, description or suggestion.

Property	Type	Required	Description
`title`	String	Conditional	Rich card title. Maximum length: 200 characters.
`description`	String	Conditional	Rich card description. Maximum length: 2,000 characters.
`media`	Object	Conditional	Media displayed in the rich card. It follows the same media restrictions as a media-only message.
`suggestions`	Array	No	Suggested replies or actions associated with the card. Maximum: 4 elements per card.

Standalone rich card

Standalone card properties

Property	Type	Required	Description
`cardOrientation`	Enum	Yes	Card orientation. Accepted values: `VERTICAL` or `HORIZONTAL`.
`thumbnailImageAlignment`	Enum	Conditional	Thumbnail alignment for a horizontal card. Accepted values: `LEFT` or `RIGHT`.
`cardContent`	Object	Yes	Content displayed in the card.

Media properties in a rich card

Property	Type	Required	Description
`height`	Enum	No	Media preview height. Accepted values: `SHORT`, `MEDIUM` or `TALL`.
`contentInfo`	Object	Yes	Media URL, optional thumbnail URL and MIME type.

The API defines the following media preview heights: 112 DP for SHORT, 168 DP for MEDIUM and 264 DP for TALL. If the media dimensions do not match the selected height, the image may be zoomed and centrally cropped.

Standalone rich card example

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

Rich card carousel

A carousel contains between 2 and 10 cards.

Each element of cardContents follows the rich card content rules, including a maximum of four suggestions per card.

Carousel properties

Property	Type	Required	Description
`cardWidth`	Enum	Yes	Width applied to the cards in the carousel. Accepted values: `SMALL` or `MEDIUM`.
`cardContents`	Array	Yes	Cards displayed in the carousel. The array must contain between 2 and 10 elements.

Carousel example

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

Suggestions

Suggestions allow the recipient to reply or perform a predefined action directly from the RCS conversation.

The following suggestion types are supported:

suggested reply;
open URL;
dial a phone number;
view a location;
share the recipient's location;
create a calendar event.

Each element of the suggestions array must contain exactly one suggestion type.

Common suggestion limits

These limits apply to all supported RCS suggestion types.

Property	Maximum length
Suggestion text	25 characters
`postbackData`	2,000 characters
Open URL	2,048 characters

Suggested reply

A suggested reply displays a predefined response to the recipient.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion and returned as the suggested reply. Maximum: 25 characters.
`postbackData`	String	Yes	Data returned to the client when the recipient selects the suggestion. Maximum: 2,000 characters.

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

Open URL action

Opens a URL when selected by the recipient.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion. Maximum: 25 characters.
`url`	String	Yes	URL to open. Maximum: 2,048 characters.
`postbackData`	String	Yes	Data associated with the action. Maximum: 2,000 characters.

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

Dial action

Starts a telephone call to the specified number.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion. Maximum: 25 characters.
`phoneNumber`	String	Yes	Telephone number in E.164 format, for example `+351211234567`.
`postbackData`	String	Yes	Data associated with the action. Maximum: 2,000 characters.

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

View location action

Displays a specified geographical location.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion. Maximum: 25 characters.
`latitude`	Decimal	Yes	Latitude in the range -90 to 90.
`longitude`	Decimal	Yes	Longitude in the range -180 to 180.
`label`	String	No	Description or label associated with the location. Maximum: 100 characters.
`postbackData`	String	Yes	Data associated with the action. Maximum: 2,000 characters.

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

Location content is supported as a suggestion action. Location content is not currently supported as the main content of a rich card. A static map image can instead be referenced through the rich card's media URL.

Prompts the recipient to share their current location.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion. Maximum: 25 characters.
`postbackData`	String	Yes	Data associated with the action. Maximum: 2,000 characters.

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

Create calendar event action

Allows the recipient to create a calendar event.

Property	Type	Required	Description
`text`	String	Yes	Text displayed in the suggestion. Maximum: 25 characters.
`title`	String	Yes	Calendar event title. Maximum: 100 characters.
`description`	String	No	Calendar event description. Maximum: 500 characters.
`startTime`	DateTime	Yes	Event start date and time in ISO 8601 format.
`endTime`	DateTime	Yes	Event end date and time in ISO 8601 format. It must be later than `startTime`.
`postbackData`	String	Yes	Data associated with the action. Maximum: 2,000 characters.

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

Batch request example

The following example sends three independent RCS messages through a single HTTP request.

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

Processing behaviour

Submitting the request does not necessarily mean that the messages have already been delivered to their recipients.

When a request is accepted:

the request is authenticated;
the organization and its access to the RCS channel are validated;
each message and its content are validated;
the available RCS balance is validated;
the accepted messages are submitted for asynchronous processing.

Final delivery can depend on factors outside the Arpoone API, including:

whether the recipient is reachable through RCS;
whether the recipient's network supports the RCS agent;
the RCS capabilities supported by the recipient's device;
the validity and availability of referenced media;
downstream provider and operator processing.

HTTP responses

The operation follows the standard Arpoone transactional API response format.

HTTP status	Result
200 OK or 202 Accepted	The request was accepted for processing.
400 Bad Request	The request contains invalid data or content.
401 Unauthorized	Authentication is missing or invalid.
403 Forbidden	The authenticated user or organization is not authorized to use the operation.
404 Not Found	A referenced organization or another required resource was not found.
402 Payment Required or existing balance status	The organization does not have sufficient RCS balance.
429 Too Many Requests	The applicable request rate limit was exceeded.
500 Internal Server Error	An unexpected error occurred while processing the request.
503 Service Unavailable	The service is temporarily unavailable.

Errors

In case of errors, the error property within in the response will be populated with an object containing information about the error that occurred:

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

The code property specifies the type of error that occurred, while the param property specifies which parameter in the RCS send payload caused the error.

The complete list of error codes can be found here.

Access the API Reference

Send RCS

Request structure​

Request properties​

Root object​

Message object​

Content rules​

Examples​

Request limits​

Text messages​

Text message example​

Text message with suggested replies​

Media messages​

Content information properties​

Media URL requirements​

Supported media types​

Images​

Video​

Documents​

Media message example​

Rich cards​

Card content properties​

Standalone rich card​

Standalone card properties​

Media properties in a rich card​

Standalone rich card example​

Rich card carousel​

Carousel properties​

Carousel example​

Suggestions​

Common suggestion limits​

Suggested reply​

Open URL action​

Dial action​

View location action​

Share location action​

Create calendar event action​

Batch request example​

Processing behaviour​

HTTP responses​

Errors​