Understand how you can use Send Message API v2 to send RCS messages.
Please Note
The RCS channel is supported viaWebex Connect Send Message API v2.
The API endpoint for it is: [https://{YourRegion}.webexconnect.io/v2/messages].
Please modify YourRegion in the URL to reflect your tenant’s region. See Know your endpoint page.
Refer to our Postman Collection for trying various types of RCS messages supported by Webex Connect.
Note
- Some mobile network RCS service providers wait for a text message delivery receipt prior to sending any related suggestion. Ensure that your test plans include each carrier your program will terminate to.
- The 'fileMessage' and 'richCardMessage' parameter fileSize requested is related to image and videos contained in URLs. The measurement will be in bytes, and while not all MaaPs require an accurate fileSize, the value of the size should not be 0.
- Please note that the substitutions apply only to 'Text' field.
RCS supports the following message types:
Messaging API v2 - Samples
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional,applicable only for text content type.
"{{rcs_parameter1}}": "{{rcs_value1}}"/
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional,applicable only for text content type.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
//Optional
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": { //Mandatory
"type": "text",
"text": "This is the message. Reply Yes or No.",
"suggestions": [ //Optional
{
"type": "reply",
"displayText": "Yes",
"postbackData": "usr_msg_yes"
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
]
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //Optional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Send Message API v2 for RCS channel: Common Body Parameters
The following are the parameters of the request body:
Parameter | Type | Mandatory | Description |
---|---|---|---|
channel | string | yes | The value needs to be 'RCS' when sending RCS messages. |
from | string | yes | The rcsAppId of the respective RCS asset setup in Webex Connect platform used for sending the message. |
to | JSONArray | yes | An array of destination MSISDNs / phone numbers to which the RCS message has to be sent in E.164 format e.g., +44xxxxx. |
msisdn | JSONArray | yes | Phone number, i.e., msisdn to which the RCS message has to be sent in E.164 format e.g., +44XXXXXXXXXX Note: If +E.164 format is enabled for your tenant - all the numbers in the to field should follow the "+E.164" format. This format displays the number with a "+" followed by the country code and the phone number. +E.164 format does not apply to the numbers in the from field. |
substitutions | JSONObject | no | List of key-value pairs for dynamic fields in the RCS message content. They are typically used to specify the values for dynamic fields in an RCS template. There are two ways to define the 'substitutions' parameter - one inside the 'to' block and another outside the 'to' block. The 'substitutions' parameter inside the 'to' block takes precedence over the 'substitutions' block that is outside the 'to' block, in case these values are provided in both places. Note: substitutions are applicable only for the text content type |
correlationId | string | no | User-defined ID that is assigned to an individual message for unique identification. |
options | JSONObject | no | A JSON object that contains additional, RCS-specific options such as smsFallback,smsSenderID, and Text in the API. |
smsFallback | boolean | no | When true, auto SMS fallback will be tried for RCS failures. If this parameter is not passed, SMS fallback will be disabled by default. Refer to the note below for details on how it works. Note: If the smsFallback parameter is set to 'true' in the Webex Connect messaging API to enable SMS fallback for RCS messages, then the smsSenderId and text fields become mandatory, to ensure that the fallback message is sent successfully. For more information on how the feature works, refer to the FAQs chapter . |
smsSenderId | string | Mandatory if smsFallback is true, else optional | Sender ID that is already configured on your account |
text | string | Mandatory if smsFallback is true, else optional | Text message up to 1024 chars |
requestedReceipts | JSONArray | no | A JSON array that can filter message delivery webhooks to the notifyUrl. Can contain one or more of the following: "Sent", "Delivered", "Read", "Failed" Check Outbound Webhooks for delivery receipt samples. |
content | JSONObject | yes, if the template is not provided | It is the JSON object that contains mandatory parameters 'type' and 'text' for the RCS channel. |
type | string | yes | Used for specifying the message content type. Acceptable values is 'text'. Please note that 'text' supports many common special characters as per the RCS specification and is preferred where possible. |
text | string | yes | The RCS message content. A maximum of 1024 characters can be supported. |
suggestions | Array object | No | Suggestions is a JSON array that can contain up to 10 suggestions with a message, 2 when within a carousel and 4 when within a richcard. These are the following suggestion types: reply viewLocation shareLocation openUrl calendarEvent dialPhone For more information, refer to section below. |
callbackData | string | no | A string that is returned with each outbound webhook for the message (delivery, failed, etc.). The maximum number of characters allowed in callbackData including any spaces is 2000. |
notifyUrl | string | no | If provided, updates related to the delivery status of this message will be posted to this URL. Refer to this page for notification samples. |
contactPolicy | JSONObject | no | JSON Object will specify contact policy checks before sending the outbound RCS message. The Contact Policy App should be configured to use this feature as a prerequisite. |
contactPolicyGroup | string | yes (if you want to apply Contact Policy checks before sending the message) | The GroupID is to be applied. It is required if any of the following options are included and set to true. |
channelCheckConsent | boolean | no | Optional, assumed false if not specified. Set to true to require opt-in before sending the message. At least one of the “channelCheckConsent” or “channelApplyFrequencyCap” parameters should be set to “true”. |
channelApplyFrequencyCap | boolean | no | Optional, assumed false. Set to true to enforce group frequency cap for that channel. At least one of “channelCheckConsent” or “channelApplyFrequencyCap” parameters should be set to “true”. |
Suggestions Object:
For each of these message type, various suggestions are possible to configure. Currently, 5 types of suggestions are supported - Reply, Viewlocation, Sharelocation, dialphone, and Calendarevent.
SuggestionType: Reply
Suggested replies help your chatbot guide users through conversations by providing responses that the chatbot knows how to react to. Your agent sends replies in suggestion chip lists or rich cards.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes,Mandatory if this type of suggestion is added | If the type is reply, the displayText and postbackData are subsequent parameters to be passed. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
postbackData | string | no | The preconfigured response to the display text selected by the user. |
SuggestionType: viewLocation
The View location action displays a location in the user's default map app. You can specify the location either by latitude and longitude.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes,Mandatory if this type of suggestion is added | If the suggestion type is viewLocation, the address,displayText, latitude, longitude, and postbackData are subsequent parameters to be passed. |
address | string | no | The configured location of the user. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
latitude | int | yes | The latitude of the configured location. |
longitude | int | yes | The longitude of the configured location. |
postbackData | string | no | The preconfigured response to the display text selected by the user |
SuggestionType: shareLocation
The Share location action lets the user send a location to your chatbot.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes,Mandatory if this type of suggestion is added | If the suggestion type is shareLocation, the displayText and postbackData are subsequent parameters to be passed. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
postbackData | string | no | The preconfigured response to the display text selected by the user |
SuggestionType: openUrl
The Open URL action opens the user's web browser to the specified URL. If an app is registered as a default handler for the URL, the app opens instead, and the icon for the action is the app's icon.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes,Mandatory if this type of suggestion is added | If the suggestion type is openUrl, the displayText, URL, and postbackData are subsequent parameters to be passed. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
URL | string | yes | The URL to which the user will be redirected upon clicking on openURL. |
postbackData | string | no | The preconfigured response to the display text selected by the user |
SuggestionType: calendarEvent
The Create calendar event action opens the user's calendar app and begins to create a new event with the specified information.
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | Yes, mandatory if this type of suggestion is added | If the suggestion type is calendarEvent, the displayText,startTime,endTime,meetingTitle,meetingDescription, and postbackData are subsequent parameters to be passed. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
startTime | string | yes | The timestamp of the scheduled calendar event can be added to the calendar. For example, 2024-09-26T13:47:18.000Z - UTC |
endTime | string | yes | Timestamp of the calendar event when it is supposed to end. For example, 2024-09-26T13:47:18.000Z - UTC |
meetingTitle | string | yes | Meeting title of the calendar event. |
meetingDescription | string | no | Details of the meeting that is scheduled by the user. |
postbackData | string | no | Preconfigured response to the display text selected by the user. |
SuggestionType: dialPhone
The Dial action guides the user to dial a phone number that your chatbot specifies.
Parameter | Value | Mandatory | Description |
---|---|---|---|
type | string | Yes, mandatory if this type of suggestion is added | If the suggestion type is dialPhone the displayText, phone and postbackData are subsequent parameters to be passed. |
displayText | string | yes | This text is usually a short, user-friendly prompt that conveys the main content or action of the RCS message. |
phone | yes | Configured phone number of the user. | |
postbackData | string | no | Preconfigured response to the display text selected by the user. |
Limitation
The routing of SMS messages will be handled by the standard routing rules configured for your tenant. Please reach out to your account manager for more information
Sample Response Body
{
"requestTimestamp": "2024-09-05T00:03:01.708-04:00",
"messageId": "a770f205-1234-3x5x-x5x3-6dc3e388b9b5",
"correlationId": "12345",
"status": "queued"
}
{
"code": "7000",
"message": "Invalid JSON"
}
No response body
Examples
RCS Media
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": {
"type": "media",
"mediaContentUrl": "https://asset.com/asset.jpg",
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
]
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //Optional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Following are the parameters required for sending message using RCS Media:
Parameter | Type | Mandatory | Description |
---|---|---|---|
type | string | yes | Used for specifying the message content type. The acceptable value is 'media'. |
mediaContentUrl | string | yes, if type = media | a publicly accessible direct media Url ending in the attachment mimeType |
RCS Standalone Card
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": {
"type": "standalone",
"richCard": {
"title": "",
"description": "",
"orientation": "",
"thumbnailAlignment": "LEFT",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2J5i2x0"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //OPtional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Following are the parameters required for sending message using RCS Standalone Card
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | Used for specifying the message content type. The acceptable value is 'standalone'. |
richCard | JSONObject | yes, if type = standalone | A JSON object containing rich card data and suggestions |
title | string | yes | Title of the message or content |
description | string | no | It indicates the content of the message |
orientation | string | yes | The orientation of the image that is being sent, can be horizontal or vertical. |
thumbnailAlignment | string | yes | The alignment of the thumbnail can be left or right. |
media | JSON Object | yes | Media includes images, video, or .gif files messages |
height | string | yes | The height of the media file can be "SHORT/MEDIUM/TALL" |
url | string | yes | The url where the media file has to be shared. |
RCS Carousel
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": {
"type": "carousel",
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
},
{
"type": "shareLocation",
"displayText": "",
"postbackData": ""
},
{
"type": "openUrl",
"displayText": "",
"url": "",
"postbackData": ""
},
{
"type": "calendarEvent",
"displayText": "",
"startTime": "{{TimeinUTC}}",
"endTime": "{{TimeinUTC}}",
"meetingTitle": "",
"meetingDescription": "",
"postbackData": ""
},
{
"type": "dialPhone",
"displayText": "",
"phone": "",
"postbackData": ""
}
],
"width": "SMALL/MEDIUM",
"cards": [
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2J5i2x0"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
},
{
"title": "",
"description": "",
"media": {
"height": "SHORT/MEDIUM/TALL",
"url": "https://bit.ly/2P5Q9dK"
},
"suggestions": [
{
"type": "reply",
"displayText": "",
"postbackData": ""
},
{
"type": "viewLocation",
"address": "",
"displayText": "",
"latitude": 0,
"longitude": 0,
"postbackData": ""
}
]
}
]
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //Optional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Following are the parameters required for sending messages using RCS Carousel:
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | Used for specifying the message content type.The acceptable value is 'carousel'. |
width | string | yes, if type = carousel | A parameter that indicates the width of carousel cards |
cards | JSONArray | yes, if type = carousel | A JSON array containing carousel card objects and their suggestions |
title | string | yes | Title of the message card of the respective card |
description | string | no | It indicates the text content of the message |
media | JSON Object | yes | Media includes images, videos, or .gif files |
height | string | yes | A parameter that indicates the height of the media shared as SHORT/MEDIUM/TALL". |
url | string | yes | The url of the media that is being shared. |
RCS Typing
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": {
"type": "agentEvent",
"event": "IS_TYPING"
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //Optional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Following are the parameters required for sending message using RCS Typing:
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | Used for specifying the message content type. The acceptable value is 'agentEvent'. |
event | string | yes, if type = agentEvent | A typing event is to be sent to the customer. |
RCS Read
{
"channel": "rcs", //Mandatory.
"from": "{{rcsAppId}}", //Mandatory.
"to": [
{
"msisdn": [
"{{msisdn}}" //Mandatory. E.164 format required/recommended.
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"correlationId": "" //Optional. The CorrelationID is a unique identifier that you can attach to every request as a reference a particular transaction or event. This is configured as a part of the request.
}
],
"substitutions": { //Optional.
"{{rcs_parameter1}}": "{{rcs_value1}}"
},
"options": {
"smsFallback": true,
"smsSenderId": "{{senderid}}",
"text": "fallback text"
},
"requestedReceipts": [ //Optional.
"DELIVERED"
],
"content": {
"type": "agentEvent",
"event": "READ",
"messageId": ""
},
"callbackData": "", //Optional. Data that you have configured to receive on the notify Url. This is configured as a part of the request.
"notifyUrl": "", //Optional.
"contactPolicy": { //Optional.
"contactPolicyGroup": "", //the GroupID to be applied. Required if any of the following options are included and set to true
"channelCheckConsent": true, //optional, assumed false, set to true to require opt-in before sending the message,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
"channelApplyFrequencyCap": true //optional, assumed false, set to true to enforce group frequency cap for that channel,“channelCheckConsent” or “channelApplyFrequencyCap” either of the parameter should be “true”
}
}
Following are the parameters required for sending message using RCS Read:
parameter | type | mandatory | description |
---|---|---|---|
type | string | yes | Used for specifying the message content type. The acceptable value is 'agentEvent'. |
event | string | yes, if type = agentEvent | A reading event is to be sent to the customer. |
messageId | string | Unique ID generated to record the messages sent using RCS read. |