> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Onboard as an RCS Provider in MoEngage > Standard payload formats for sending RCS template messages and standard callback formats for delivering callback information to 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: 1. 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. 2. After implementation, MoEngage will provide a staging environment with the RCS module enabled. To access this environment, contact the MoEngage Partnership Team. 3. 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. 4. Share a user guide covering aspects like configuring your connector in MoEngage and callbacks in your platform. 5. Share the results of the test case execution with MoEngage. 6. 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. 7. 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** ```text theme={null} --header 'Authentication: Bearer ' \ ``` ### 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](#rcs). | | sms | Optional | Object | This field denotes the details of the SMS message. For more information, refer to [sms](#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: ```json theme={null} { "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: ```json theme={null} { "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: ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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. | ### Share Location ```json theme={null} { "type": "REQUEST_LOCATION", "text": "Suggestion text", "postback_data": "postback data string" } ``` ### Create Calendar Event ```json theme={null} { "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: ```json theme={null} "cid_user_id_appId_timestamp" ``` ## Header Note that you can pass any custom arguments for authentication in headers. ```json theme={null} Content-Type: application/json // Default header Authentication: {{auth}} // Any custom headers ... ``` ## Sample cURL Request ```bash theme={null} curl --location '' \ --header 'Content-Type: application/json' \ --header 'Authentication: Bearer ' \ --data '' ``` ## 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** ```json theme={null} [{ "status": "SUCCESS | FAILURE", "message": "ERROR_DESCRIPTON", "callback_data": CALLBACK_DATA }, { ... } ] ``` **4XX** ```json theme={null} { "message": "ERROR_DESCRIPTON" } ``` **5XX** ```json theme={null} { "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 ```json theme={null} { "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 ```json theme={null} { "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** ```json theme={null} { "status": "SUCCESS" } ``` **4XX** ```json theme={null} { "status": "FAILURE", "error_message": "Invalid Request Body" } ```