Before You Begin
OpenMarket's RCS messaging APIs let you send messages that have the look and feel of a mobile app with the ease and simplicity of an SMS message. Following are brief descriptions of the key capabilities of our RCS service, with links into the technical documentation so you can see exactly how to make use of them.
Handset capability check and SMS Fallback
When sending an RCS message, our system performs a capability check to determine whether the end user's phone can receive and properly display an RCS message. If you send an RCS message that includes a rich card and chip list (set of action buttons), then our capability check will determine which phones are UP 2.0-compliant. We will send the RCS message to those phone numbers only. If you send us an RCS message that does not include UP 2.0 elements, then our capability check will determine which phones are UP 1.0- and 2.0-compliant and we'll send the message to those phone numbers.
To deliver an RCS message to end users whose phones do not support RCS, your campaign should utilize our SMS fallback feature. When using this feature, your RCS message will be sent as an SMS message to phones that don't support RCS. To use SMS fallback, we'll configure your OpenMarket account to use both the Invoke API (used for RCS) and our Global SMS API (used for SMS). Make sure to ask your OpenMarket account manager about SMS fallback and its features.
To see how to include SMS fallback in a message request, see Invoke API Parameters.
Auto-response to MO messages
When an end user replies to a message that you've sent, our system can respond automatically with a predefined message. For example, if your MT message gives the user the option to contact your support team, you might provide a 'Support' button for the user to tap, or let the user text "support" back for more help. In response to the end user's MO message, you could send back a message thanking the end user for getting in touch and letting them know what the next step is. Auto-response is very useful for standard MOs like "help" and "stop", enabling you to instantly respond to users with useful information.
For more information on how auto-response works, see "Using auto-response for a free text keyword reply" in Receive an RCS MO.
Custom branding, colors, and rich media content
With RCS messaging you have the ability to custom-brand the message with your company's logo and colors, and include rich media content such as images, video, and rich cards (also called carousels). These elements give your RCS message the look and feel of a mobile app, but with the simplicity of a text message. To learn about the feedback OpenMarket's early RCS customers got from their users, see our Why use RCS blog post.
A chip list is a set of buttons that suggest a reply or an action. When the end user taps a chip (a button), an MO message is sent that triggers the next step in a predefined workflow. For example, an RCS message promoting a concert could have buttons that let the user link to a web page or purchase tickets. Both of these buttons trigger different workflows.
For information see the suggestion parameter in Invoke API parameters.
Just like SMS and MMS, RCS messaging always needs to provide the end user with a way to opt out. With RCS the user experience is the same as SMS in that an end user can text STOP or tap a "Stop" button if one is provided.
Our system has the ability to automatically add opted-out users to a blacklist, ensuring that they do not receive future messages. You also have the ability to set up an auto-response to a STOP message, to assure the end user that you received their request and that they won't be sent additional messages.
When you send an RCS message, you can receive a read receipt, which simply tells you whether the end user opened the message. Delivery receipts, which are sent from the mobile operator, provide basic information about the message's status. To receive read or delivery receipts, you'll need to provide us with endpoints for where to send the receipts. You'll do this during the onboarding process. For technical details see RCS Delivery and Read Receipts.
RCS messages contain rich media such as images, video, and interactive elements like rich cards and action buttons. You'll need to store the media files for these elements in a content management system (CMS). You can use your own or use ours. For more information on how to upload media files to our CMS, see Media Upload API.
Use this feature in conjunction with auto-responder to deliver localized responses to each country. For instance, when an end user in Canada texts HELP, your system can respond with "For help go to website.ca", rather than pointing the user to a general mywebsite.com. For more information about using auto-response, see "Auto-response and multiple languages" Receive an RCS MO.
Data and reporting
OpenMarket provides an RCS Detailed data source that you can use to create reports through the Reporting Insights tool in our Customer Center. The data source contains information you can use to understand how many messages were sent and delivered, which countries messages were sent to, message type (MT or MO), message status, and more.
For details about the data source, see RCS Detailed data source.
RCS message flows
The following two diagrams give you a high-level understanding of what happens as an RCS MT message moves from your system to the end user's handset, and what happens when an MO message is sent from the end user to our system.
MT message flow
- Your system sends a message request to our Invoke API, which authenticates your request, performs various validity checks, and returns response codes so you know whether the request was accepted and processed.
- OpenMarket's RCS platform makes several decisions, such as whether the destination phone number is a handset that's capable of receiving an RCS message and which MaaP and mobile operator to use.
- If the destination handset is RCS-capable, we send the message to it via the MaaP and mobile operator.
If the handset is not RCS-capable and you are using our SMS fallback capability, we send the SMS message to the handset via our Global SMS API. If the phone is not RCS-capable and you are not using SMS fallback, the message will fail delivery.
- The end user receives the message on their handset, either as an RCS or SMS message depending on the capability of the device.
MO message flow
- The end user replies to an RCS message either by sending a text or tapping a chip (also known as an action button).
- Our service identifies which type of reply the end user sent.
- Our service decides whether to forward the MO to your system.
- If you opted to receive MOs for both text and chip replies, we send it to the address you provided to us in advance.
How we process a text reply
When our system receives a text MO, we can take different actions based on how you want to manage the flow. Here are a couple of examples:
- Let's say an end user texts STOP. If you want to receive that MO so that you can use it in your own tools, then you'll provide us with an endpoint where we can send it. Another option is to not receive the MO but instead have us automatically take a predefined action. For example, we can automatically add the user to a blacklist and send an MT to the user assuring them they will not receive any further messages.
- Let's say an end user texts in the keyword, SUPPORT. We match it with a list of keywords that you've provided to us in advance and map those keywords to a predefined workflow, which might include sending an MT back to the user with information about how to contact a support representative.
How we process a chip reply
We respond to a chip MO based on an optional parameter that you include in your MT message request called customerData. When you include this parameter, an MO is sent to us when the end user taps a chip. That MO can include information such as the MSISDN.
We can forward chip MOs to you assuming you provide us in advance with an endpoint to send them to.