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:

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

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:

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

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