Sending RCS

RCS (Rich communication services) is a protocol between both mobile operators and phones. The overall aim of RCS is for it to eventually replace SMS and MMS messaging, the formats we're all familiar with as they have been around for years. That is, RCS is a set of communication standards for SMS, MMS, and calling that make text messages look and feel more like dedicated messaging apps like WhatsApp, Telegram, Facebook Messenger, among others. It aims to bring "texting" up to the modern standards with features we expect from messaging apps.

Before you can send messages to users, you need to register as a partner with RCS Business Messaging. As a partner, you can create agents for brands that you manage and send messages through those agents.

An agent is a conversational entity that interacts with users by sending messages and reacting to users' responses. Messages between a user and an agent appear in an RCS-enabled messaging app, such as the Messages app, on the user's device. The Messages app displays branding and profile information for your agent, including name, logo, description, contact information, and URLs.

RBM agents use the RCS Business Messaging API to send messages, events, and other requests to users. When you create an agent, you enable access to the RBM API and define your agent's name and region.

The steps to create an Agent are the following:

  1. Open the Business Communications Developer Console and sign in with your RBM Platform Google account.

  2. Click Create Agent.

  3. Enter your agent's name and region, then click Create agent.

  4. When your agent is available, click your agent's name.

To send messages and events as your agent, you need to authenticate API calls with a service account key. The Business Communications Developer Console creates a service account for you, but you need to create a unique key to access your agent.

The steps to create a service account key to access the RBM API as your agent, and configure your agent to receive messages.

  1. Open the Business Communications Developer Console and sign in with your RBM Platform Google account.

  2. In the left navigation, click Service account.

  3. Click Create key, then click Create. Your browser downloads a service account key for your agent. Store the key in a secure location on your development machine. The key can't be recovered if lost.

Once you have created and configured the agent, copy your Agent ID; you will need it to send the RCS message to the recipient.

We provided you the ability to create a simple text message and a standalone rich card with suggestions sent from the agent to the final user.

Each of the following documents will give you example requests for the message types and rendered messages on handsets.

Messaging API supports sending two types of RCS messages:

  • Text

  • Standalone Rich Card

We even provided you the ability to send the message via SMS in case the message couldn't be delivered by RCS.

📘

NOTE

The total number of API Calls (requests) that the user can make to the POST /notification endpoint in a certain time has been limited. That is, in case the user exceeds the limit of requests (messages sent) that can be made in a specific time, he/she will not be able to send another request until the established time is up. Once the time has elapsed, the request counter is reset and the request can be sent to the endpoint again.

In this example, the user can send 2 requests in 300 seconds (5 minutes). When a third request is sent within the 5 minute range, the HTTP Status Code “429” will be generated and the following parameter will be displayed from the Response body: "errors": { "reason": Too Many Requests" }. This code tells you that the user has sent too many requests in a given amount of time. Once the required time has elapsed, the request counter is reset to 2, so the user will be able to send two requests again in 5 minutes.

To find out if the user exceeds the limit of required requests and the time he/she needs to wait to send the next request, we recommend consulting the Response Header (additional information about the body of the resource). The parameters presented in the response header are the following:

ratelimit-limit: 2
ratelimit-policy: 2;w= 300
ratelimit-remaining: 1
ratelimit-reset: 5m0s

  • RateLimit-Limit: return the number of requests left for the client in the time window
  • RateLimit-Remaining: return the remaining quota in the current window
  • RateLimit-Reset: return the time remaining in the current window, specified in seconds
  • RateLimit-Policy: return the quota policy. The quota policy expression can be found in paragraph 2.1 of the IETF draft. The format is, for example, for 2 requests in 300 seconds.

Text RCS Message

The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response. Simple use cases like notifications, alerts, or conversational chats can be composed in Text.

When you send a simple Text RCS message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "RCS",
  "request": {
    "to": "+580000000005",
    "message": "text demo",
    "messageType": "TEXT",
    "agentId": "604af472d06abe3a6f5c852e"
  }
}

By default, this request attempts to deliver the message via the RCS channel.

If you want to ensure message delivery in case the RCS channel is unavailable, you can enable RCS fallback. This feature allows your message to be automatically sent as an SMS if RCS delivery fails.

To enable the fallback function, you must include additional parameters in the request body as shown below:

{
  "channel": "RCS",
  "request": {
    "to": "+580000000005",
    "message": "Welcome to Elipackage",
    "messageType": "TEXT",
    "agentId": "604af472d06abe3a6f5c852e",
    "fallbackMessage": "Welcome to Elipackage",
    "fallback": [
      {
        "type": "SMS",
        "from": "141518"
      }
    ]
  }
}

The parameters presented in the request body example when sending the simple Text RCS message are the following:

Parameter Required Description
channel Yes

Specifies the type of delivery channel which the notification message will be sent: "SMS", "EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "RCS" value to send the RCS message.

request Yes Message content.
request.to Yes Determines the destination phone number for your RCS message.

Numbers are specified in E.164 format → (‘+’ and a country code).

request.message Yes The content of the RCS message that will be sent to the end user.
request.messageType Yes

Describing the type of message which is going to be sent over RCS.

"TEXT" : Identifies the RCS message as an RCS text message.

"STANDALONECARD" : Identifies the RCS as a Rich Card.

In this case, we enter the "TEXT" value to send a simple text RCS message.

request.agentId Yes Agent's unique identifier. Set by RCS Business Messaging.
request.fallbackMessage No Enter the content of the message that will be sent via SMS if the RCS delivery fails.
request.fallback No

Array of fallback objects containing the alternative channel configuration to use when RCS message delivery fails.

RCS only works for Android devices that support RCS messaging.

fallback.from No

Source address of the message.

Specifies the Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier.

If you don't have one assigned yet please contact our support team to request one.

fallback.type No

Specifies the fallback channel to use. Currently, the only supported value is "SMS".

request.externalId No Alphanumeric identifier used for reporting purposes.
request.clientId No Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.

The parameters presented in the response body example when sending the simple Text RCS notification message are the following:

Parameter Description
meta "meta" segment is dedicated to metadata regarding the call itself.
meta.timestamp

Call’s time mark.

Sequence of characters identifying when the message has been sent.

meta.transactionId Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta.explain Useful message regarding the operation or the call.

The Messaging API publishes the RCS message in the RCS API queue; for this reason, the response generates the “meta” segment.

Standalone Rich Card

A Standalone Rich Card is a small snippet, usually an image, that's linked to additional actions. This card can contain a suggested reply or a suggested action (suggestion).

Standalone Rich cards can contain the following items:

  • Image/video

  • Title text

  • Description text

  • A list of suggested replies and suggested actions (maximum 4)

When you send a Standalone Rich Card RCS message, the request body contains the following data:

HTTP Request : POST / notification

{
  "channel": "RCS",
  "request": {
    "messageType": "STANDALONECARD",
    "title": "sample title",
    "cardImageUrl": "https://example.url.site/logo.png",
    "mediaHeight": "SHORT",
    "cardOrientation": "HORIZONTAL",
    "alignment": "RIGHT",
    "to": "+580000000005",
    "agentId": "604af472d06abe3a6f5c852e",
    "suggestions": [
      {
        "type": "REPLY",
        "text": "Yes"
      },
      {
        "type": "REPLY",
        "text": "No"
      }
    ]
  }
}

By default, this request attempts to deliver the message via the RCS channel.

If you want to ensure message delivery in case the RCS channel is unavailable, you can enable RCS fallback. This feature allows your message to be automatically sent as an SMS if RCS delivery fails.

To enable the fallback function, you must include additional parameters in the request body as shown below:

{
  "channel": "RCS",
  "request": {
      "messageType": "STANDALONECARD",
      "title": "sample title",
      "cardImageUrl": "https://example.url.site/logo.png",
      "mediaHeight": "SHORT",
      "cardOrientation": "HORIZONTAL",
      "alignment": "RIGHT",
      "to": "+580000000005",
      "agentId": "604af472d06abe3a6f5c852e",
      "suggestions": [
          {
              "type": "REPLY",
              "text": "Yes"
          },
          {
              "type": "REPLY",
              "text": "No"
          }
      ],
      "fallbackMessage": "Welcome to Elipackage",
      "fallback": [
          {
              "type": "SMS",
              "from": "141518"
          }
      ]
   }
}

The parameters presented in the request body example when sending the Standalone Rich Card RCS message are the following:

Parameter Required Description
channel Yes

Specifies the type of delivery channel which the notification message will be sent: "SMS", "EMAIL", "PUSH", "RCS", "WHATSAPP".

In this case, we enter the "RCS" value to send the RCS message.

request Yes Message content.
request.to Yes Determines the destination phone number for your RCS message.

Numbers are specified in E.164 format → (‘+’ and a country code).

request.messageType Yes

Describing the type of message which is going to be sent over RCS.

"TEXT" : Identifies the RCS message as an RCS text message.

"STANDALONECARD" : Identifies the RCS as a Rich Card.

In this case, we enter the "STANDALONECARD" value to send a Standalone Rich Card RCS message.

request.agentId Yes Agent's unique identifier. Set by RCS Business Messaging.
request.title Yes Title of the card.
request.mediaHeight Yes

Height of the card media.

Values: "SHORT", "MEDIUM", "TALL"

request.cardOrientation Yes

Orientation type defines orientation in Card message.

Values: "HORIZONTAL", "VERTICAL"

request.alignment Yes

Alignment type defines alignment in Card message.

Values: "LEFT", "RIGHT"

request.cardImageUrl Yes URL of the given resource. Type the URL of the image that is included in the card.
request.suggestions Yes List of suggestions comprised of suggested replies and suggested actions.
suggestions.text Yes Text that will be shown in the suggested reply.
suggestions.type Yes

Users can tap a suggested reply to send the text reply back to the agent.

Value: "REPLY"

request.description No Description of the card.
request.fallbackMessage No Enter the content of the message that will be sent via SMS if the RCS delivery fails.
request.fallback No

Array of fallback objects containing the alternative channel configuration to use when RCS message delivery fails.

RCS only works for Android devices that support RCS messaging.

fallback.from No

Source address of the message.

Specifies the Shortcode (from 1 to 6 digits), Longcode (from 7 digits on), an alphanumeric shortcode (ex. COMPANY) or a virtual number that will be used to originate and send the SMS message. Any of these codes will appear in the handset as the source of the text message. Virtual numbers will translate to a local shortcode depending on the destination carrier.

If you don't have one assigned yet please contact our support team to request one.

fallback.type No

Specifies the fallback channel to use. Currently, the only supported value is "SMS".

request.externalId No Alphanumeric identifier used for reporting purposes.
request.clientId No Unique user identifier that can be used for reporting purposes. This is an identifier you can use to uniquely identify the destination address in your systems. This is similar to the externalId and will be sent back to you if you are requesting callbacks that contain status changes of the messages you send.

The parameters presented in the response body example when sending the standalone rich card RCS notification message are the following:

Parameter Description
meta "meta" segment is dedicated to metadata regarding the call itself.
meta.timestamp

Call’s time mark.

Sequence of characters identifying when the message has been sent.

meta.transactionId Call’s transaction ID, this will help our teams to locate issues faster if arose.
meta.explain Useful message regarding the operation or the call.

The Messaging API publishes the RCS message in the RCS API queue; for this reason, the response generates the “meta” segment.