Invoke API
Invoke API Parameters
These are the details of the Invoke API, including descriptions and sample usage. The API is composed of these parameters:
- endUser
- variables and request
- rcs and sms
- rcs
- text
- media
- richCard
- messageOrder
- card
- media
- suggestion
- reply
- action
- urlAction
- dialAction
- locationAction
- calendarAction
- sms
For complete examples of the Invoke API, see Invoke API Message Examples.
endUser
The endUser field sets the destination for the RCS message.
|
Parameter |
Description |
|---|---|
|
phoneNumber |
The mobile or landline phone number of the end user. This must be in international format but without a leading + symbol. For example, "447700900765" (UK) or "12515550100" (US). You can only specify one phone number in this request. Type: string, between six to 16 characters. The phone number must be enclosed within quotes (" ") and must contain only digits. Required: yes |
|
mobileOperatorId
|
A numeric ID representing the mobile operator as known by OpenMarket. For a list of mobile operator IDs see Mobile Operator IDs. Type: integer Required: no |
Example usage
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},variables and request
An RCS message is always first formatted using both a variables and a request element. These elements will directly follow the endUser.
Example usage
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": <values>,
"media": <values>,
"richCard": <values>
},
"sms": {
"messageContent": <value>
}
}
}
}
The request element is composed of the elements that form the RCS message and the backup SMS message that's sent if the recipient's handset does not support RCS. It's composed of two elements, rcs and sms.
|
Parameter |
Description |
|---|---|
|
rcs |
Indicates the type of RCS to send. It must be text, media, and/or richCard. You can have multiple RCS types, but you must have at least one type specified. See text, media, or richCard for more information.. Type: object Required: At least one of text, media, or richCard is required. |
|
sms
|
Indicates that an SMS will be sent in the event that an RCS message can't be received by the receiver. This typically occurs if the phone is not RCS-capable. See sms for more information. Type: object Required: No |
An RCS message is always first formatted using both a variables and request element. These elements will directly follow the endUser .
Example usage
In this example, an RCS message is being sent. In the event that the recipient's handset does not support RCS, an sms will instead be sent.
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!"
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
} rcs
The rcs field element further defines the RCS message by indicating what type of RCS message is being sent: text, media, and/or richCard. You can send multiple types, but you must send at least one type.
|
Parameter |
Description |
|---|---|
|
text |
Identifies the RCS message as an RCS text message. See text for more information. Type: object Required: At least one of text, media, or richCard is required. |
|
media
|
Identifies the RCS message as an RCS media message. An RCS media message can be a video or an image. Type: object Required: At least one of text, media, and/or richCard is required. |
| richCard |
Identifies the RCS as a Rich Card. A Rich Card is a small snippet, usually an image, that's linked to additional actions. For example, a Rich Card can be used to dial a phone number, access a website, or open a map. You can send multiple Rich Cards in a message. Type: object Required: At least one of text, media, and/or richCard is required. |
| order |
Sets the order with a messageOrder array for determining which an RCS type is displayed on the recipient's handset if multiple types are sent. If no order is passed, the default order is by media object type: text, media, and then richCard. See messageOrder for more information. Type: object Required: No |
Example usage
This example sends text and media types.
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!"
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"suggestions": [
{
"action": {
"displayText": "Our website!",
"url": "http://www.mysite.com"
}
}
]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}text
The text element further defines the parameters of an RCS text message.
|
Parameter |
Description |
|---|---|
|
message |
Message displayed to the recipient. Type: string Required: Yes. The size can be between 1 and 8192 bytes. Message concatenation is not supported. If the size is greater than the allowed limit the message will be rejected. |
|
id
|
The order in which an RCS type is displayed. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering. Type: string Required: No |
| suggestions |
Array of suggestion objects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions for text only appear if text is the last item on the screen. Type: collection Required: No |
Example usage
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!"
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}media
The media type further defines an RCS media message. For example, the RCS message might be a JPEG linked to a website.
|
Parameter |
Description |
|---|---|
|
fileUrl |
Link to a media file. The full path must be used. The URL must use https:// and must link to a media file in OpenMarket's CMS. See Media Upload API Version 1 for information on uploading media files. Type: string Required: Yes |
|
mimeType
|
Indicates the type of media file. For example, this might be image/jpeg. Type: string Required: Yes |
| fileSize |
The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 12367 bytes. Type: integer Required: Yes. The maximum file size can be no more than 100 mb. |
| thumbnailURL |
The URL to the image thumbnail, if a thumbnail is used. The full path must be used, starting with https://. Type: string Required: No |
| thumbnailMimeType |
The image mime type. For example, this might be image/jpeg. Type: string Required: Yes, but only if included the thumbnailURL. Otherwise, no. |
| thumbnailFileSize |
The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have JPEG that is 125 bytes. Type: integer Required: Yes, but only if you included the thumbnailURL. Otherwise, no. The maximum size of he thumbnail can be no more than 10 kb. |
| id |
Used for ordering the media type. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering. Type: string Required: No |
| suggestions |
Array of suggestion objects. For example, this could be a link to a website or to place a call. The order of the list of suggestions is determined by their placement in the JSON request. In addition, suggestions for media only appear if media is the last item on the screen. Type: collection Required: No |
Example usage
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!"
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}richCard
The richCard media type defines one or more "cards" that display on the recipient's handset. These cards can then be associated with actions, such as dialing a phone number, pinning a map location, or accessing a website.
|
Parameter |
Description |
|---|---|
|
cardOrientation |
Sets how a rich card is oriented. cardOrientation is used only when a single Rich Card is sent. Type: string Required: No. However, if passed, cardOrientation must be one of the following:
|
|
imageAlignment
|
Indicates an image on a Rich Card. imageAlignment is used only when a single Rich Card is sent. Type: string Required: No. However, if passed, imageAlignment must be one of the following:
|
| cardHeight |
The height of a card when used when a single Rich Card is sent or the height of all Carousel Cards. Type: string Required: No. However, if passed, cardHeight must be one of the following:
|
| cardWidth |
The width applied to all cards in a Carousel. Type: string Required: No. However, if passed, the cardWidth must be one of the following:
|
| cards |
Defines the cards in an array. A single card is treated as a single Rich Card. Multiple cards are treated as a Carousel. See card for more information about this array. Note: There must be at least one card in this array. Type: card Required: Yes |
| id |
The order in which an RCS type is displayed. Each id must then be passed in the order parameter in rcs. The order in which this id is added to the order is the order in which it will display on the recipient's handset. See order in rcs for information about how the id field is used for ordering. Type: string Required: No |
Example usage
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardOrientation": "HORIZONTAL",
"imageAlignment": "LEFT",
"cardHeight": "MEDIUM",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
},
{
"reply": {
"displayText": "Reply now!",
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}messageOrder
The messageOrder field sets the display order of text, media, and richCard objects on a recipient's handset.
|
Parameter |
Description |
|---|---|
|
messageOrder |
To use the messageOrder parameter, you must set a string for the id parameter of that RCS type. The string must then be added to order in the order in which you want them displayed. When passed in this parameter, each id should be enclosed within double quotes (" "), each id separated by a comma (,). The entire parameter should then be enclosed in brackets ([ ]). For example, if you have a text type with an id of text1, a media type with an id of media1, and an richCard with id of richcard1, you could set the order as ["richcard1", "media1", "text1"]. The RCS type will then display on the recipient's handset in the id order set here. Type: array of string. Required: yes, but only if using the order element. |
Example usage
In this example, a text RCS type uses an id of text1 and a media RCS type uses an id of media1. The messageOrder is arranged by media1 and then text1 so that the media RCS type displays first, followed by the text RCS type.
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!",
"id": "text1",
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"id": "media1"
},
"order": {
"messageOrder" : ["media1", "text1"]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}card
card contains the information for a single card, such as specifying a graphic for the card, an action to take when clicking the card, and the descriptive text that appears on the card.
|
Parameter |
Description |
|---|---|
|
title |
Text that displays on the card. Type: string Required: At least one of title, description, or media is required, but any combination of these three is valid. However, if used, you must use UTF-8 encoding. The maximum size of the title should be no more than 200 characters. |
|
description
|
Descriptive text that appears on the card. Type: string Required: At least one of title, description, or media is required, but any combination of these three is valid. The maximum number of characters is 2,000. |
| media |
Defines media, such as graphics, that you want to display in a card. For example, this might be an image with a linked URL. See media for more information. Type: object Required: At least one of title, description, or media is required, but any combination of these three is valid. |
| suggestions |
Array that of suggestion objects. For example, this might be opening a website or dialing a phone number. Type: array Required: No. Any combination of these three is valid; however, the maximum number of suggestions for a single richCard is three — for example, this might be three replies, three actions, or two actions and one suggestion. A maximum of two suggestions is allowed for each card in a carousel. See "cardHeight" in richCard for information about carousel cards. |
Example usage
In this example, a Rich Card is defined with multiple cards which are then displayed as a carousel.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardWidth": "SMALL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
},
{
"title": "Place call!",
"media": {
"fileUrl": "https://www.myurl.com/mythirdfile.mp4",
"mimeType": "video/mp4",
"fileSize": 42367
},
"suggestions": [
{
"action": {
"displayText": "Call us!",
"dialAction": {
"phoneNumber": "+12223334444"
}
}
}
]
},
{
"title": "Location Nearby!",
"media": {
"fileUrl": "https://www.myurl.com/mylastfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Store near you!",
"locationAction": {
"latitude": "+47",
"longitude": "+122"
}
}
}
]
},
{
"title": "Calendar!",
"media": {
"fileUrl": "https://www.myurl.com/mysecondfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Put it on your calendar!",
"calendarAction": {
"startTime": "2018-01-02T15:01:23Z",
"endTime": "2018-01-03T16:01:23Z",
"title": "Your appointment",
"description": "Here are the details for your appointment"
}
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}media
media defines the card associated with the Rich Card. This might include displaying the Rich Card with a graphic.
|
Parameter |
Description |
|---|---|
|
fileUrl |
Link to a media file. Link to a media file. The full path must be used. The URL must use https:// and must link to a media file in OpenMarket's CMS. See Media Upload API Version 1 for information on uploading media files.. Type: string Required: Yes |
|
mimeType
|
Indicates the type of media file. For example, this might be image/jpeg. Type: string Required: Yes |
| fileSize |
The size of the media file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 12367 bytes. Type: integer Required: Yes |
| thumbnailURL |
The URL to the image thumbnail, if a thumbnail is used. The full path must be used, starting with https://. Type: string Required: No |
| thumbnailMimeType |
The image mime type. For example, this might be image/jpeg. Type: string Required: No |
| thumbnailFileSize |
The size of the thumbnail image file, in bytes. Different mobile operators have different size limits. For example, you might have a JPEG that is 125 bytes. Type: integer Required: Yes |
Example usage
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardOrientation": "HORIZONTAL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
},
{
"reply": {
"displayText": "Reply now!"
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}suggestion
suggestion is an object that defines either an action or a reply for the RCS type.
|
Parameter |
Description |
|---|---|
|
action |
Defines the action to take for the click action. Each possible action is composed of further information, dependent on the action taken. See action for more information. Type: object Required: A suggestion must have either an action or a reply, but at least one. |
|
reply
|
Defines the reply. See reply for more information. Type: object Required: A suggestion must have either an action or a reply, but at least one. |
Example usage
In this example, the suggestions parameter is an array with both an action suggestion and a reply suggestion.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardOrientation": "HORIZONTAL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
},
{
"reply": {
"displayText": "Reply now!"
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}reply
A reply prompts the recipient with display text to perform the requested suggestion.
|
Parameter |
Description |
|---|---|
|
displayText |
The text displayed to the recipient when the suggestion is a reply. Type: string Required: Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number requires the end user to scroll through the text to read the entire text. |
| customerData |
When passed in a request, this parameter allows information about the tapped reply to be returned to you as an MO that the specific reply was tapped. This MO can include additional information about the customer, such as an MSISDN. For example, a reply might be an option to dial a phone number. The parameter should be unique for each reply if multiple reply suggestions are included. Type: string. If you want the response returned as JSON, you must escape quotes with \". For example Required: No. However, if this parameter is not passed no information is returned to you. |
Example usage
In this example, a suggested reply includes a customerData parameter that returns information when an end user taps the reply to contact customer service.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardOrientation": "HORIZONTAL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
},
{
"reply": {
"displayText": "Reply now!"
"customerData": "{\"buttonText\":\"Reply Now!\",\"sugestionChipId\":\"EXAMPLEID-001\",\"phoneNumber\":\"12065551234\"}"
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}action
Defines the action to take when the user clicks a media type if an action is defined for suggestions.
|
Parameter |
Description |
|---|---|
|
displayText |
Displays the text the recipient sees for that action. For example, this might be Call us!or Reply now. Type: string Required: Yes. The maximum number of characters, including white spaces, is 25. We recommend that you use no more than 10 characters as a larger number would require the end user to scroll through the text to read the entire text. |
| customerData |
When passed in a request, this parameter allows information about the tapped action to be returned to you as an MO that the specific action was tapped. This MO can include additional information about the customer, such as an MSISDN. The parameter should be unique for each action if multiple action suggestions are included. Type: string. If you want the response returned as JSON, you must escape quotes with \". For example, Required: No. However, if this parameter is not passed no information is returned to you. |
|
urlAction
|
Clickable URL. This parameter is further refined in urlAction. Type: object Required: Exactly one of the following is required in the action object:
|
|
dialAction
|
Links to the phone dialer, allowing the recipient to call the number associated with the dialAction. This parameter is further refined in dialAction. Type: object Required: Yes. Must be one of the following:
|
|
locationAction
|
Links to the location passed into the locationAction, allowing the recipient to open their default map application and see that location. This parameter is further refined in locationAction. Type: object Required: Exactly one of the following is required in the action object:
|
|
calendarAction
|
Links to the recipients calendar, allowing the recipient to add information to their calendar. For example, this might be used if an RCS message is sent reminding the recipient of an appointment. This parameter is further refined in calendarAction. Type: object Required: Exactly one of the following is required in the action object:
|
Example usage
In this example, multiple Rich Cards are sent. Within the urlAction parameter, a customerData parameter is included that indicates when this action is selected by an end user. Because customerData is not used within the dialAction and locationAction parameters, no information is returned when those actions are selected by the end user.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardWidth": "SMALL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our Website!",
"customerData": "UserClickOnWebsite",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
},
{
"title": "Place call!",
"media": {
"fileUrl": "https://www.myurl.com/mythirdfile.mp4",
"mimeType": "video/mp4",
"fileSize": 42367
},
"suggestions": [
{
"action": {
"displayText": "Call us!",
"dialAction": {
"phoneNumber": "12223334444"
}
}
}
]
},
{
"title": "Location Nearby!",
"media": {
"fileUrl": "https://www.myurl.com/mylastfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Store near you!",
"locationAction": {
"latitude": "+47",
"longitude": "+122"
}
}
}
]
},
{
"title": "Calendar!",
"media": {
"fileUrl": "https://www.myurl.com/mysecondfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Put it on your calendar!",
"calendarAction": {
"startTime": "2018-01-02T15:01:23Z",
"endTime": "2018-01-03T16:01:23Z",
"title": "This is the appointment title",
"description": "This is a description of the appointment"
}
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}urlAction
urlAction links a URL to the Rich Card. When the user clicks the Rich Card, the website is accessed from the URL added in this parameter.
|
Parameter |
Description |
|---|---|
|
url |
Full path to a website. The URL must begin with either http:// or https:// Type: string Required: Yes |
Example usage
In this example, a single Rich Card is sent with urlAction as the single associated action.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardOrientation": "HORIZONTAL",
"cards": [
{
"title": "My Website!",
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Our website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
},
{
"reply": {
"displayText": "Reply now!"
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}dialAction
dialAction links a phone number to the Rich Card. When the user clicks the Rich Card, the user is prompted to call the number added here.
|
Parameter |
Description |
|---|---|
|
phoneNumber |
Phone number to dial. Use an alphanumeric source address using the international E.164 format; <country code> followed by the <national number>. For example, +12223334444. Type: string Required: Yes |
Example usage
In this example, multiple Rich Cards are sent. One of the Rich Cards includes the dialAction.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardWidth": "SMALL",
"cards": [
{
"title": "Place call!",
"media": {
"fileUrl": "https://www.myurl.com/mythirdfile.mp4",
"mimeType": "video/mp4",
"fileSize": 42367
},
"suggestions": [
{
"action": {
"displayText": "Call us!",
"dialAction": {
"phoneNumber": "+12223334444"
}
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}
locationAction
locationAction opens a map on the user's handset, with the location added here pinned to the map.
|
Parameter |
Description |
|---|---|
|
latitude |
The latitudinal coordinate. Type: string Required: Yes. Must be in the range [-90.0, +90.0]. |
|
longitude |
The longitudinal coordinate. Type: string Required: Yes. Must be in the range [-180.0, +180.0]. |
| label |
Text associated with the pin displayed on the map. Type: string Required: No |
Example usage
In this example, multiple Rich Cards are sent. One of the Rich Cards includes the locationAction.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardWidth": "SMALL",
"cards": [
{
"title": "Location Nearby!",
"media": {
"fileUrl": "https://www.myurl.com/mylastfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Store near you!",
"locationAction": {
"latitude": "+47",
"longitude": "+122"
}
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}
calendarAction
calendarAction prompts the recipient to add a meeting or appointment request to their handset's calendar, using the start and end times added to this parameter.
|
Parameter |
Description |
|---|---|
|
startTime |
The beginning time in RFC 3339 UTC Zulu format, accurate to seconds. For example, 2017-10-02T15:01:30Z. Type: string Required: Yes |
|
endTime |
The ending time in RFC 3339 UTC Zulu format, accurate to seconds. For example, 2017-10-02T16:01:45Z. Type: string Required: Yes |
| title |
Text associated with the pin displayed on the map Type: string Required: Yes. You must use UTF-8 encoding. The maximum size of the title should be no more than 4096 bytes |
| description |
Description associated with the calendar event. Type: string Required: Yes |
Example usage
In this example, a Rich Card is sent with a single action, calendarAction.
{
"endUser":{
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables":{
"request":{
"rcs": {
"richCard": {
"cardWidth": "SMALL",
"cards": [
{
"title": "Calendar!",
"media": {
"fileUrl": "https://www.myurl.com/mysecondfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367
},
"suggestions": [
{
"action": {
"displayText": "Put it on your calendar!",
"calendarAction": {
"startTime": "2018-01-02T15:01:23Z",
"endTime": "2018-01-03T16:01:23Z",
"title": "This is the appointment title",
"description": "This is a description of the appointment"
}
}
}
]
}
]
}
},
"sms":{
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}
sms
When used, the sms parameter sends a fallback SMS message in the event the end user's phone does not support RCS. You must first be provisioned to use this feature. When used, sms fallback uses the HTTP Global SMS API. Events related to SMS can then be found in the SMS Activity Search. customerData is not supported in an SMS message.
Note: UTF-8 is the only supported character set for an SMS fallback. If your message content is greater than the supported number of characters, your message is rejected with a v4 HTTP rejected request message. Contact your Account Manager and work with them to split your messages into multiple segments or reduce the number of characters in the message. Please note that if you choose to segment your message, your carrier might charge you for each sent segment.
|
Parameter |
Description |
|---|---|
| messageContent |
The message to be displayed on the recipient's handset. Type: string Required: Yes |
| sourceTon |
The MO source address type of number (TON). Type: string Required: No. If used, however, valid values are:
|
Example usage
In this example, an SMS message will be passed instead of an RCS message if the recipient's handset does not support RCS.
{
"endUser": {
"phoneNumber": "12065551234",
"mobileOperatorId": "77"
},
"variables": {
"request": {
"rcs": {
"text": {
"message": "Hello customer!"
},
"media": {
"fileUrl": "https://www.myurl.com/myfile.jpg",
"mimeType": "image/jpeg",
"fileSize": 12367,
"suggestions": [
{
"action": {
"displayText": "Check out my website!",
"urlAction": {
"url": "http://www.mysite.com"
}
}
}
]
}
},
"sms": {
"messageContent": "Hello customer! Check out my website, http://www.mysite.com!"
}
}
}
}