RCS Messages APIs
The RCS Messages API is a robust HTTP-based service designed to streamline the submission of diverse message types, including plain text, rich text, and rich card messages.
This API supports a wide array of message types - from simple plain text to rich multimedia cards and interactive carousels - making it ideal for applications that require flexible and engaging communication.
Whether you are running marketing campaigns or sending transactional updates, the Messaging API provides the tools needed to deliver content effectively and interactively.
Media Types
The following media types are supported for the US region:
| Media Type | Documentation Type | Extension | Works with Rich Cards |
|---|---|---|---|
| application/ogg | OGG audio | .ogx | No |
| application/pdf | Yes (Only for Google Messages in India) | ||
| audio/aac | AAC audio | .aac | No |
| audio/mp3 | MP3 audio | .mp3 | No |
| audio/mpeg | MPEG audio | .mpeg | No |
| audio/mpg | MPG audio | .mp3 | No |
| audio/mp4 | MP4 audio | .mp4 | No |
| audio/mp4-latm | MP4-latm audio | .mp4 | No |
| audio/3gpp | 3GPP audio | .3gp | No |
| image/jpeg | JPEG | .jpeg, .jpg | Yes |
| image/gif | GIF | .gif | Yes |
| image/png | PNG | .png | Yes |
| video/h263 | H263 video | .h263 | Yes |
| video/m4v | M4V video | .m4v | Yes |
| video/mp4 | MP4 video | .mp4 | Yes |
| video/mpeg4 | MPEG-4 video | .mp4, .m4p | Yes |
| video/mpeg | MPEG video | .mpeg | Yes |
| video/webm | WEBM video | .webm | Yes |
Notes:
- The maximum size of an individual file must not exceed 100 MiB.
- The total combined size of all media and PDF attachments within a single message must not exceed 100 MiB.
RCS Message Body
The following is the RCS Message body used in RCS Message APIs:
| Field Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| From | from | String | Yes | Service code or sender ID |
| To | to | []string | Yes | Recipient mobile numbers |
| Text | text | String | Optional | Plain text message |
| Ref | ref | String | Optional | Custom reference |
| Ref1 | ref1 | String | Optional | Custom reference 1 |
| Ref2 | ref2 | String | Optional | Custom reference 2 |
| Suggestions | suggestions | *[]Suggestion | Optional | Suggested replies or actions |
| RichCardStandalone | richCardStandalone | *RichCardStandalone | Optional | Standalone rich card |
| RichCardCarousel | richCardCarousel | *RichCardCarousel | Optional | Carousel rich cards |
| File | file | *MediaFile | Optional | File message attachment |
| TTL Seconds | ttlSeconds | String | Optional | Message expiry time |
TTL (Time-to-Live) Seconds
The following table outlines common use cases and their recommended TTL values.
| Use Case | Recommended TTL |
|---|---|
| OTP / Transactional | 300–900s (5–15 min) |
| Alerts / Notifications | 1–6 hours |
| Marketing / Campaigns | 24–48 hours |
| Long-lived messages | Maximum 7 days (T-Mobile, Verizon) |
Note:
The AT&T carrier default value of TTL is set to 72 hours (when it is not explicitly mentioned in the request payload).
RichCardStandalone
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| CardOrientation | cardOrientation | String | Yes | Vertical / Horizontal |
| ThumbnailImageAlignment | thumbnailImageAlignment | String | Optional | Image alignment |
| Content | content | *RichCardStandaloneContent | Yes | Card content |
RichCardStandaloneContent
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| Title | height | String | Yes | Card title |
| Description | description | String | Yes | Card description |
| Media | media | *MediaContent | Optional | Media content |
| Suggestions | suggestions | *[]Suggestion | Yes | Actions or replies |
MediaContent
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| Height | height | String | Yes | Media height |
| File | file | *MediaFile | Optional | Media file |
MediaFile
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| FileUrl | fileUrl | String | Yes | File URL |
| ThumbnailUrl | thumbnailUrl | String | Yes | Thumbnail URL |
| ContentDescription | contentDescription | String | Yes | File description |
RichCardCarousel
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| CardWidth | cardWidth | String | Yes | Card width |
| CardContents | cardContents | *[]RichCardCarouselContent | Yes | Carousel cards |
RichCardCarouselContent
| File Name | JSON Key | Type | Required | Description |
|---|---|---|---|---|
| Title | title | String | Yes | Card title |
| Description | description | String | Yes | Card description |
| Media | media | *MediaContent | Yes | Media content |
| Suggestions | suggestions | *[]Suggestion | Yes | List of suggestion items to be displayed to the end user as quick reply options. |
Benefits
- Flexibility: Supports a wide range of message types for different use cases.
- Interactivity: Chiplists and suggestions enhance user engagement.
- Rich Media Support: Enables visually appealing and informative messaging.
Key Use Cases
Following a set of key use cases is presented; of course, you can use RCS messages for any other use cases fitting your purposes and interactions with end-users.
Marketing Campaigns
Send promotional messages using rich cards and carousels to showcase products, offers, or events.
Use chiplists and suggestions to guide users toward specific actions like “Buy Now” or “Learn More.”
Customer Engagement
Deliver personalized messages with rich multimedia content to enhance user experience.
Use rich text and chiplists to provide interactive FAQs or support options.
Testing and QA
Submit test traffic with various message types to validate rendering on different mobile display and backend processing.
Ensure compatibility across devices and platforms by simulating different message types.
Interactive Surveys and Feedback Collection
Use chiplists and suggestions to create quick-response surveys.
Rich cards can be used to present questions with visual context.
Transactional Messaging
Send order confirmations, delivery updates, or appointment reminders using plain or rich text formats.
Include actionable links or chiplists for rescheduling or tracking.
This API supports the following message types:
- RCS Suggestions
- Send a File Message
- Send a Plain Text Message
- Send a Plain Text Message with URL
- Send a Plain Text Message with URL and ChipList
- Send a Plain Text Message with ChipList
- Send a Rich Text Message
- Send a Rich Text Message with Chiplist
- Send Rich Card Standalone Message
- Send a Rich Card Standalone Message with a Chiplist
- Send a Rich Card Standalone Message with a Suggestion
- Send a Rich Multimedia Text Message
- Send a Rich Card Carousel Message with Chiplist
- Send a Rich Card Carousel Message with Suggestion
- RCS Delivery Receipt (DR) Callback Events
- RCS Mobile Originated (MO) Callback Events
- RCS Mobile Originated (MO) Events
Updated 9 days ago