Onboard as an RCS Provider in MoEngage

This article describes the standard payload formats that MoEngage uses for sending RCS template messages and standard callback formats for delivering callback information to MoEngage. This article describes how to onboard as an RCS provider in MoEngage. It provides the standard payload formats that MoEngage uses to send RCS template messages and standard callback formats to deliver callback information to MoEngage.

Onboard Yourself as a Native RCS Service Provider

Follow the process below if you want to become an RCS provider in MoEngage:

Complete the implementation and development of your internal messaging infrastructure to match the payload formats for the MoEngage request and Callbacks using the formats shared in the respective sections.
After implementation, MoEngage will provide a staging environment with the RCS module enabled. To access this environment, contact the MoEngage Partnership Team.
Configure your API and callback integration within the MoEngage staging environment. You must then execute and validate the specific test scenarios provided by MoEngage to ensure message delivery and status reporting function correctly.
Share a user guide covering aspects like configuring your connector in MoEngage and callbacks in your platform.
Share the results of the test case execution with MoEngage.
After sharing the results of the test case execution and the user guide:
- The MoEngage engineering team (QA) reviews the test case execution and validates the integration.
- The MoEngage documentation team reviews the user guide.
After the quality checks are performed, MoEngage lists you as one of the native RCS providers in MoEngage and publishes the user guide as the partner guide of MoEngage.

Message Payload Details

This section details the message payload in the request that MoEngage sends to your API.

API Endpoint/URL

This is the API endpoint or API URL of the RCS partner to whom MoEngage sends the message payload. The RCS partner must provide this URL.

Sample Request Headers

You must share information about the headers to be added to the request, such as the API Key, Workspace ID, and Authorization. For example, if the authentication to be used is Bearer Authentication, MoEngage will add the same in the authorization header in the request, as shown in the following sample: Sample Header

--header 'Authentication: Bearer <client auth token to be used by vendor>' \

Request Body

This is the request that MoEngage sends to your API.

Key	Optional/Required	Data type	Description
messages	Required	Array	An array of objects having messages to be sent, which can be a bulk or a single object. The maximum limit is 50 characters.
destination	Required	String	The field denotes the phone number to which the RCS message is sent. Ensure that this is in E.164 format.
callback_data	Required	String	String to be reverted to MoEngage in every callback. This helps with reconciliation.
fallback_order	Required	String	In the case of RCS only, this is sent as `["rcs"]`. In the case of RCS with SMS as fallback, this is sent as `["rcs","sms"]`.
rcs	Required	Object	This field denotes the object containing the RCS message and contains keys specific to RCS and the type of RCS message. For more information, refer to rcs.
sms	Optional	Object	This field denotes the details of the SMS message. For more information, refer to sms. Note: Only present if fallback as SMS is selected by the client.

rcs

Key	Optional/Required	Data type	Description
rcs[“bot_id”]	Required	String	This field denotes the agent ID registered for sending the RCS message.
rcs[“template_id”]	Optional	String	This field is present only for messages sent to an Indian mobile number.
rcs[“message_content”]	Required	Object	This field denotes the entire RCS template content.

sms

Key	Optional/Required	Data type	Description
sms[“sender”]	Required	String	This field denotes the registered sender of the SMS.
sms[“template_id”]	Optional	String	This field is present only for messages sent to an Indian mobile number.
sms[“message”]	Required	String	This field denotes the entire SMS content.

Sample Payload

To ensure compatibility across all RCS vendor integrations, MoEngage uses a standardized, generic payload. This payload is designed to accommodate the two primary processing methodologies currently used by vendors:

Parameter-based processing: The vendor expects dynamic message content as a discrete set of parameters.
Resolved text processing: The vendor expects the fully resolved message text (where MoEngage merges the dynamic content into the complete text string prior to sending).

The payloads detailed below include the necessary data to satisfy both requirements. Vendors can extract and process the payload according to their supported methodology. The following is a sample payload for sending RCS messages:

{
 "messages":[
          {
        "destination": "phone number", // sent in E.164 format
        "callback data": CALLBACK__DATA, // string to be sent back in callback
        "fallback_order": ["RCS","SMS"]
        "rcs": {
            "bot_id": "bot id entered" // Agent id registered for RCS messages
            "template_id": "template id", // Optional string for Indian templates
            "message_content": MESSAGE_CONTENT
           }
        "sms": {
            "sender": "sender id of fallback"
            "message": "Message text", // resolved message
            "template_id": "template id" // Optional string for Indian templates 
            }
         },
           {
             ...
           }
       ]
  }

Sample Payload for Indian Users

The following is a sample payload for sending RCS messages to users in India:

{
 "messages":[
       {
      "destination": "+9191986468797",
      "callback_data": "1235_Moe123_0602947568495588_22455667qwrt888qq9",
      "fallback_order": ["RCS","SMS"],
      "rcs": {
          "bot_id": "AjyAJTVPcvlFzpMR",
          "template_id": "Onboarding_1",
          "message_content": {
                     "type": "CARD",
                     "data": {
                     "media": {
                          "media_url":
                           "https://cdn.openart.ai/uploads/image_MZNLY6Kp_1732684235696_raw.jpg",
                           "content_type": "IMAGE"
              },
                    "title": "Welcome John to Moengage",
                    "description": "John is happily welcomed to Moengage and will be a crucial part of
the Product team",
                    "orientation": "HORIZONTAL",
                    "height": "",
                    "alignment": "LEFT",
                    "parameters": {
                       "name": "John",
                       "company": "Moengage",
                       "teamname": "Product"
                   }
                },
         "suggestions": {
                  "type": "REPLY",
                  "text": "STOP Messaging",
                  "postback_data": "STOP"
                   }
               }
             },
  "sms": {
  "message": "Hi John, Welcome to Moengage as you dont have RCS you get SMS",
  "template_id": "Onboarding_SMS_1",
  "sender": "Sender_2"
       }
   },
{
 ...Other messages..
    }
 ]
}

Sample Payload for International Users

The following is a sample payload for sending RCS messages to international users:

{
  "messages": [
    {
       "destination": "+919137470627",
       "callback_data": "1235_Moe123_060222455677788_22455667qwrt888qq9",
        "fallback_order": ["RCS","SMS"],
             "rcs": {
              "bot_id": "AjyAJKFTbdlFzpMR",
              "template_id": null,
               "message_content": {
                   "type": "CARD",
                    "data": {
                      "media": {
                        "media_url": "https://cdn.openart.ai/uploads/image_MZNLY6Kp_1732684235696_raw.jpg",
                        "content_type": "IMAGE"},
                        "title": "Welcome John to Moengage",
                        "description": "John is happily welcomed to Moengage and will be a crucial part of
the Product team",
                        "orientation": "HORIZONTAL",
                        "height": "",
                        "alignment": "LEFT",
                        "parameters": {
                                       "name": "John",
                                       "company": "Moengage",
                                       "team_name": "Product"
                          }
                     },
                        "suggestions": {
                                   "type": "REPLY",
                                   "text": "STOP Messaging",
                                   "postback_data": "STOP"
                        }
                    }
                  },
                 "sms": {
                     "message": "Hi John, Welcome to Moengage as you dont have RCS you get SMS",
                     "template_id": null,
                     "sender": "Sender_2"
                 }
           },
      {
      ...Other messages..
       }
     ]
}

Limitations

This is a bulk API that supports a message limit of 50 user messages.
For vendors that do not support bulk sending, MoEngage sends only one user message in the messages array.
The default timeout is 5 seconds. Make sure your infrastructure accepts and responds within 5 seconds.

Message Content for Text

{
   "type": "TEXT",
   "data": {
        "text": "Text message to be sent",
        "parameters": {
                 "param_1": "value_1",
                  ...
                }
             },
   "suggestions": [SUGGESTION_1, SUGGESTION_2...]
 }

Key	Optional/Required	Data Type	Description
type	Required	String	This field denotes the type of templates. Supported values are: TEXT, CARD, MEDIA, CAROUSEL
data[“text”]	Required	String	This field denotes the resolved text. This is for vendors who do not support dynamic parameters. They can use this to do string matches.
data[“parameters”]	Required	String	This field contains all the dynamic parts of the message for vendors who do not use resolved text. They can use dynamic parameters.
suggestions	Optional	Array	This field contains suggestions like reply, calendar event, etc.

Message Content for Card

{
   "type": "CARD",
      "data": {
          "media": {
               "media_url": "media_url",
               "content_type": "content type",
               "thumbnail": {
                     "thumbnail_url": "thumbnail_url"
                       }
               },
            "title": "Title message",
            "description": "Description of the card",
            "orientation": "HORIZONTAL | VERTICAL",
            "height": "SHORT | MEDIUM",
            "alignment": "LEFT | RIGHT",
            "parameters": {
                   "param_1": "value_1",
                   ...
                 }
              },
              "suggestions": [SUGGESTION_1, SUGGESTION_2 ...]
 }

Key	Optional/Required	Data Type	Description
media[“media_url”]	Required	String	This field denotes the URL of the media to be included in the card.
media[“content_type”]	Required	String	This field denotes the content type of the media. Supported values are: PDF, VIDEO, IMAGE
media[“thumbnail”]	Optional	Object	This field denotes the thumbnail information.
title	Required	String	This field denotes the resolved title. This is for vendors who do not support dynamic parameters can use this to do a string match.
description	Optional	Array	This field denotes the resolved description. This is for vendors who do not support dynamic parameters. They can use this to do a string match.
orientation	Required	String	This field denotes the media orientation. Supported values are: HORIZONTAL, VERTICAL
height	Optional	String	This field denotes the media height. Supported values are: SHORT, MEDIUM. Note: This field is optional only in case of vertical orientation.
alignment	Optional	String	This field denotes the media alignment. Supported values are: LEFT, RIGHT. Note: This field is optional only in case of horizontal orientation.

Note: Other parameters remain the same as specified above, hence not mentioned, but for reference, check above.

Message Content for Carousel

{
"type": "CAROUSEL",
"data":{
    "width": "SMALL | MEDIUM",
    "cards":[
        {
           "data":{
             "media":{
                 "media_url": "media_url",
                 "content_type": "content type",
                 "thumbnail":{
                     "thumbnail_url": "thumbnail_url"
                     }
                  },
              "title": "Title message",
              "description": "Description of the card",
              "orientation": "HORIZONTAL | VERTICAL",
              "height": "SHORT | MEDIUM",
              "alignment": "LEFT | RIGHT",
              "parameters":{
                  "param_1": "value_1",
                       ...
                 }
              },
      "suggestions":[SUGGESTION_1, SUGGESTION_2 ...]
              },
             {
            ...card 2 body...
            }
          ]
       }
    }

Key	Optional/Required	Data Type	Description
width	Required	String	This field denotes the width of the carousel
cards	Required	Array of Card Template Object	This field contains the list of card template objects

Note: Other parameters remain the same as specified above, hence not mentioned, but for reference, check above.

Message Content for Media Message

{
   "type": "MEDIA",
   "data": {
      "media_url": "media_url",
      "content_type": "content type",
      "thumbnail":{
                  "thumbnail_url": "thumbnail_url"
              }
       },
   "suggestions": SUGGESTIONS
}

Suggestions

Following are the types of suggestion JSON objects:

Reply

{
   "type": "REPLY",
   "text": "Suggestion text",
   "postback_data": "postback data string"
}

Key	Optional/Required	Data Type	Description
type	Required	String	This field denotes the type of suggestions. Supported values are: OPEN_URL, DIAL_PHONE, SHOW_LOCATION, QUERY_LOCATION, REQUEST_LOCATION, CREATE_CAL_EVENT
text	Required	String	This field denotes the text to be shown as a reply.
postback_data	Required	String	This field denotes the text to be sent back to MoEngage for reconciliation.

Open URL

{
   "type": "OPEN_URL",
   "text": "Suggestion text",
   "postback_data": "postback data string",
   "url": "url",
   "application": "WEBVIEW" | "BROWSER",
   "webview_view_mode": "FULL"| "HALF" | "TALL"
}

Key	Optional/Required	Data Type	Description
url	Required	String	This field denotes the URL specified for redirection.
application	Optional	String	This field denotes that the application is opened in a browser or a webview.
webview_view_mode	Optional	String	This field is required only if a webview is used within the application.

Dial Phone

{
   "type": "DIAL_PHONE",
   "text": "Suggestion text",
   "postback_data": "postback data string",
   "phone": "phone number"
}

Key	Optional/Required	Data Type	Description
phone	Required	String	This field denotes the phone number for dial phone suggestions.

Show Location

{
   "type": "SHOW_LOCATION",
   "text": "Suggestion text",
   "postback_data": "postback data string",
   "latitude": "latitude",
   "longitude": "longitude",
   "label": "label for location"
}

Key	Optional/Required	Data Type	Description
latitude	Required	String	This field denotes the latitude of the location.
longitude	Required	String	This field denotes the longitude of the location.
label	Optional	String	This field denotes the label text for the location.

Query Location

{
   "type": "QUERY_LOCATION",
   "text": "Suggestion text",
   "postback_data": "postback data string",
   "query": "query for location"
}

Key	Optional/Required	Data Type	Description
query	Required	String	This field denotes the location query.

{
   "type": "REQUEST_LOCATION",
   "text": "Suggestion text",
   "postback_data": "postback data string"
}

Create Calendar Event

{
   "type": "CREATE_CAL_EVENT",
   "text": "Suggestion text",
   "postback_data": "postback data string",
   "start_time": "event start time",
   "end_time": "event end time",
   "title": "event title",
   "description": "event description"
 }

Key	Optional/Required	Data Type	Description
start_time	Required	String	This field denotes the start time of the calendar event in the timestamp format.
end_time	Required	String	This field denotes the end time of the calendar event in the timestamp format.
title	Required	String	This field denotes the title of the calendar event.
description	Optional	String	This field denotes the description of the calendar event.

Callback Data

MoEngage sets the value to this string while sending the request. Ensure to return this string in the callbacks. The string can be of a maximum of 200 characters and alphanumeric with ”_” as a separation character. For example:

"cid_user_id_appId_timestamp"

Note that you can pass any custom arguments for authentication in headers.

Content-Type: application/json // Default header
Authentication: {{auth}} // Any custom headers
...

Sample cURL Request

curl --location '<api_url provided by the vendor>' \
--header 'Content-Type: application/json' \
--header 'Authentication: Bearer <client auth token to be used by vendor>' \
--data '<payload>'

Response Codes

Status Code	Request State	Description
200	Success or Failure	This response is returned when the request is processed successfully or when the request fails.
4XX	Client errors	This response is returned when a client error occurs.
5XX	Unknown errors	This response is returned when the system runs into an unexpected error.

Sample Response

200

[{
"status": "SUCCESS | FAILURE",
"message": "ERROR_DESCRIPTON",
"callback_data": CALLBACK_DATA
},
{
...
}
]

4XX

{
"message": "ERROR_DESCRIPTON"
}

5XX

{
"message": "ERROR_DESCRIPTON"
}

Key	Required	Data Type	Description
status	Required	String	This field denotes the status of the request and indicates whether the message was sent successfully or not. It is present only in the case of a 2xx response. Supported values are: Success, Failure
message	Optional	String	This field contains the description of errors when there are 4xx and 5xx errors.

Types of Callback

Callbacks Url will be provided similar to sms to the vendors. These will be public url without any authorization headers. There are two types of callback:

Message status callback
RCS suggestions interaction callback

Message Status Callback

{
"statuses": [
{
   "status": "RCS_SENT | RCS_DELIVERED | SMS_SENT | SMS_DELIVERED | RCS_READ | RCS_DELIVERY_FAILED | SMS_DELIVERY_FAILED",
   "callback_data": CALLBACK_DATA,
   "timestamp": "event timestamp epoch",
   "error_message": "User readable error message"
},
...
]
}

The following table displays the callback status and its description:

Status	Description
RCS_SENT	This status denotes that the vendor has attempted to send an RCS message to the end user.
SMS_SENT	This status denotes that the vendor has attempted to send an SMS message to the end user.
RCS_SENT_FAILED	This status denotes that an RCS message that is to be sent has failed. This contains all the rejected messages or messages for which the vendor failed to send.
SMS_SENT_FAILED	This status denotes that an SMS message that is to be sent has failed due to mobile number validation or other validations at the vendor’s end.
RCS_DELIVERED	This status denotes that an RCS message has been delivered successfully. If the SMS fallback is not included, the SMS message is not attempted.
SMS_DELIVERED	This status denotes that an RCS delivery failed, and the failover SMS is delivered successfully.
RCS_READ	This status denotes that the end user has successfully received and read the RCS message. This event is triggered exclusively following an RCS_DELIVERED status and is not applicable to SMS_DELIVERED events.
RCS_DELIVERY_FAILED	This status denotes that an RCS delivery has failed.
SMS_DELIVERY_FAILED	This status denotes that an SMS delivery has failed.

Key	Required	Data Type	Description
status	Required	String	This field denotes the callback status.
callback_data	Required	String	This field denotes the callback data.
timestamp	Required	String	This field denotes the timestamp in epoch format.
error_message	Optional	String	This field denotes an error description. Note: This field is required in case of error messages.

RCS Suggestions Interaction Callback

{
   "events": [
    {"type": "SUGGESTION_CLICKED",
    "callback_data": CALLBACK_DATA,
    "timestamp": "event timestamp epoch",
    "data": {
       "text": "Suggestion text",
       "postback_data": "postback_data"
}
},
 ...
]
}

Limitation of Callbacks

Callbacks have the following limitations:

Callbacks can be sent as a single message or a bulk batch with a maximum of 50 messages.
Callbacks can have a maximum timeout of 5 seconds at the vendor’s end. If the MoEngage infrastructure doesn’t respond in 5 seconds, retry a maximum of three times.

Callback Response

Callback response is expected with the following status and details: 200

{
      "status": "SUCCESS"
}

4XX

{
"status": "FAILURE",
"error_message": "Invalid Request Body"
}

​Onboard Yourself as a Native RCS Service Provider

​Message Payload Details

​API Endpoint/URL

​Sample Request Headers

​Request Body

​rcs

​sms

​Sample Payload

​Sample Payload for Indian Users

​Sample Payload for International Users

​Limitations

​Message Content for Text

​Message Content for Card

​Message Content for Carousel

​Message Content for Media Message

​Suggestions

​Reply

​Open URL

​Dial Phone

​Show Location

​Query Location

​Share Location

​Create Calendar Event

​Callback Data

​Header

​Sample cURL Request

​Response Codes

​Sample Response

​Types of Callback

​Message Status Callback

​RCS Suggestions Interaction Callback

​Limitation of Callbacks

​Callback Response