The Vonage Messages API now supports RCS Business messaging. If you're not already familiar with the Messages API, it's a REST API for omni-channel messaging. It provides a standardized and easy-to-use interface to send and receive messages via SMS, MMS, WhatsApp, Facebook Messenger, Viber, and now RCS!
If you've never heard of RCS before, you might be wondering "What exactly is RCS messaging?" Let's find out!
RCS, or Rich Communication Services, is a communication protocol for sending messages to, and between, devices connected to a cellular telephony network. As well as text, RCS messages can include photos, videos, files, and more.
You might be thinking that sounds a lot like MMS messaging. Well, kind of, but there are some important differences:
MMS messages can be delivered over the cellular network whereas RCS messages require a connection to the internet (either via a cellular data connection or Wi-Fi).
RCS messages also allow larger file sizes for images, videos, and files than MMS.
RCS messages allow for more interactivity than MMS, with advanced message types for displaying media and rendering buttons for suggested replies for performing specific actions such as dialing a number or opening a location in a maps app.
In many ways, RCS messaging is closer in functionality to the OTT (Over-The-Top) messaging that you may be familiar with via apps such as WhatsApp, Facebook Messenger, Viber, and others. The advantage of RCS over these other channels is that RCS messaging is supported natively in a phone's built-in messaging app rather than users having to install a third-party app on their devices.
This advantage currently comes with a major caveat, however -- device support.
RCS messaging is, currently, only supported on Android devices. In a recent press release, however, Apple stated that RCS will be supported as part of the upcoming release of iOS 18:
When messaging contacts who do not have an Apple device, the Messages app now supports RCS for richer media and more reliable group messaging compared to SMS and MMS.
The exact details of Apple support for RCS aren't known at this stage, and it's not clear if support will include RCS business messaging or be solely for peer-to-peer messaging.
Let's dig a little further into the Vonage implementation of RCS in the Messages API by looking at the various message types that can be sent and received.
The RCS channel of the Vonage Messages API leverages Google's RBM (RCS Business Messaging) servers and supports the different message types available via Google RBM. The channel supports both outbound messaging (messages sent from the business to the customer) and inbound messaging (messages sent from the customer to the business, in response to an outbound message). Within both of these categories, there are many different types of message that exist. We’ll briefly list them here before going on to look at some specific examples of a few types.
For outbound messages, some of the Google RBM message types are abstracted to specific types that you might already be familiar with from other Messages API channels, such as text, image, video, and file. There is also a custom message type that supports the more complex RBM messages such as suggested replies, suggested actions, rich cards, and carousels.
Inbound messages are received via a webhook set up in your Vonage Developer Dashboard. For RCS, there are multiple inbound message types. The type received by the webhook depends on either the content of the message sent by the customer or on how the customer interacts with a message sent by the business. The customer sending text, some sort of media, or a location will result in inbound messages of type text, image, video, audio, vcard, file, or location. The customer interacting with a suggested reply or suggested action message will result in inbound messages of type reply or button.
Finally, as with all Messages API channels, outbound RCS messages receive message status updates via a webhook (again set up in the Vonage Developer Dashboard). For RCS messages, these status updates include a read status for when the recipient of the message has read the message.
It might be easier to visualize some of these message types by looking at a few code examples, so let's do that now!
Let's look at some outbound messages first, starting with a basic text message.
As with all Messages API channels, sending an RCS message requires making a POST request to the Vonage Messages API endpoint with the appropriate JSON payload. Some of the JSON object properties, such as channel, message_type, to, and from are common across channels and message types, and some are specific to the channel and/or message type. For an outbound RCS text message, the JSON would be structured as follows:
{
"to": "447900000000",
"from": "Vonage",
"channel": "rcs",
"message_type": "text",
"text": "Hello world!"
}This would show as follows in the recipients's messaging app:
Screenshot of an RCS text message
The JSON for image, video, and file messages is similar except they need to include an object with a url property, the value of which is a publicly accessible URL for the file that you want to send. For example, the JSON to send a picture of a cat might look like this:
{
"to": "447900000000",
"from": "Vonage",
"channel": "rcs",
"message_type": "image",
"image": {
"url": "https://example.com/cat.jpg"
}
}and result in the following message being shown in the recipient's messaging app:
Screenshot of an RCS image message
All other outbound RCS messages are supported by the custom message type. These messages include a custom object containing the properties relevant to the specific message. There are too many sub-types and permutations to cover in this article, but one example might be a message with two suggested reply buttons:
{
"to": "447900000000",
"from": "Vonage",
"channel": "rcs",
"message_type": "custom",
"custom": {
"contentMessage": {
"text": "What do you think of Vonage APIs?",
"suggestions": [
{
"reply": {
"text": "They're great!",
"postbackData": "suggestion_1"
}
},
{
"reply": {
"text": "They're awesome!",
"postbackData": "suggestion_2"
}
}
]
}
}
}which would display the following:
Another example could be a suggested action message to open a URL:
{
"to": "447900000000",
"from": "Vonage",
"channel": "rcs",
"message_type": "custom",
"custom": {
"contentMessage": {
"text": "Check out our latest offers!",
"suggestions": [
{
"action": {
"text": "Open product page",
"postbackData": "postback_data_1234",
"openUrlAction": {
"url": "http://example.com/"
}
}
}
]
}
}
}which would result in the following:
Screenshot of an RCS suggested action message
Although the structure of these two message types is different, you may have noticed that both the reply and action objects contain a postbackData property. The value of this property becomes relevant in the context of the inbound message that is triggered when the suggested reply or suggested action message is interacted with by the recipient. We'll take a look at inbound messages next.
As previously mentioned, inbound messages are received via a webhook. There are several different inbound message types, and we won't cover all of them here, but we can walk through a few examples.
As with outbound messages, some fields in the JSON payload are common across all channels and message types. The to, from, channel, and message_type fields you will already have seen in the outbound messages examples above. In addition to these, inbound messages contain some other standard fields; message_uuid which is a unique identifier for the message, and timestamp which indicates the date and time the inbound message was delivered. Beyond these standard properties, what is contained in the webhook payload will depend on the message type.
Types such as text, image, video, audio, vcard, file, and location will contain data based on the message sent from the customer's device. For the types that involve some sort of media or file being sent, the payload will include a link to the file on Vonage's media servers. For example, the webhook payload for an image message might look something like this:
{
"to": "Vonage",
"from": "447900000000",
"channel": "rcs",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2024-02-08T10:12:44Z",
"context_status": "none",
"message_type": "image",
"image": {
"name": "image.jpg",
"url": "https://api-eu.nexmo.com/v3/media/6882bbe2-fe14-4e2f-910f-652bbbb058d4"
}
}The inbound reply and inbound button messages are sent as a result of customers interacting with suggested reply and suggested action messages respectively. Earlier in this article we mentioned the postbackData property in those types of outbound messages, and this is where the value set for that property comes into play.
Looking at the suggested reply example, if the customer selected the button that read They're awesome! the inbound reply message would look something like this, with the value for postbackData contained in the id property of the reply object:
{
"to": "Vonage",
"from": "447900000000",
"channel": "rcs",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2024-02-08T10:12:44Z",
"context_status": "none",
"message_type": "reply",
"reply": {
"id": "suggestion_2",
"title": "They're awesome!"
}
}An inbound button message similarly contains the value for postbackData, but this time is set as the payload property of the button object. A button message triggered by a customer opening the URL from our earlier suggested action message would look something like this:
{
"to": "Vonage",
"from": "447900000000",
"channel": "rcs",
"message_uuid": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab",
"timestamp": "2024-02-08T10:12:44Z",
"context_status": "none",
"message_type": "button",
"button": {
"payload": "postback_data_1234",
"text": "Open product page"
}
}In both these cases, the value of this postbackData can be used to identify the action taken by the customer. Logic can then be built around this to trigger further outbound messages as part of an overall message flow.
In this article, we've looked at examples of sending and receiving individual messages of different types. The potential power of RCS though, compared to channels such as SMS and MMS, is in combining those different message types to build rich, interactive messaging flows that can be used for many different transactional or marketing use cases.
RCS offers the potential for engaging messaging experiences, in a similar way to that offered by messaging apps such as WhatsApp, Facebook Messenger, and Viber. Native support for RCS on customers' devices means that they don't need to download a specific app to receive those messages thereby massively expanding the potential reach of RCS messaging compared to specific messaging app channels. The stumbling block to this reach has always been the lack of device support by Apple, but with RCS due to be supported in iOS 18 now is a great time to get started with RCS and start building it into your messaging system.
If you're excited about RCS and want to learn more, you can dive straight into our developer documentation. While you're there you can check out all the other channels that the Messages API offers or explore our many other communications APIs.
We’d also love to have you join us on the Vonage Developer Slack or send us a Post on X, and we will get back to you!
){kind=small}
