Send Message
ContentMessage
This identifies the content of a RCS message sent from the Business (Agent, ChatBot, Application) to an end-user. This attribute should be in the “body” field in SCG. A single request can include text, a rich card, an image, or a video as well as suggested replies and suggested actions. The maximum size of a message is 250KB
|
Parameter |
Description |
|
Suggestions [ ] |
suggestion is an object that defines either an action or a reply for the RCS type. This is a list of suggested replies and suggested actions that appear as a list of suggestion chips following the associated message. The user can tap a suggested reply to send the text reply back to the agent or tap a suggested action to initiate a native action on the device. There is a Max 11 suggestion chips and a maximum of 25 characters for each suggested reply or action Format: Object Required: At least one of text, media, or richCard is required, UTF-8 encoding |
|
text
|
Identifies the RCS message as an RCS text message. Type: String, UTF-8 |
|
media |
media is a file within a rich card. The media will have a height defined (enum), a filename (string) and contentInfo (Object)
|
|
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. A richCard can be a Standalone card or carousel card |
|
contentInfo |
This carries information about a file, including URL of the file and the URL of the file’s thumbnail. Type: object |
Text
The simplest messages are made of text. Text messages are best suited to communicate information without the need for visuals, complex interaction, or response. Simple use cases like notifications, alerts or conversational chats can be composed in Text.
The Text parameter can be used within the contentMessage parameter.
curl -X POST "https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H "Content-Type: application/json" \
-d "{
'contentMessage': {
'text': 'Hello, world!'
}
}"
SCG also supports simple composition of text messages using the "Body" parameter for RCS recipients similar to all other channels on the platform.
Sample Message:
curl -X POST
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H 'Authorization: Bearer {TOKEN} \
-H 'Content-Type: application/json' \
-d '{"from":"sender_id:gtz9wXVkA51HSyB5wYTcP","to":"+14081111222","body":" Hello, this is my first text message to a RCS device"}
|
Field |
Description |
|
from |
The “from” field includes the identifier that represents the customers verified identity
|
|
to |
The “to” field is the parameter that identifies the address of the recipient(s). This is usually the mobile phone number of the recipient. Type: E.164 format for example with US phone number +1-408-111-2222, the value would be “+14081112222” |
|
body |
The body field is the body of the message that contains the text message that the customer is sending to the recipient. The format is in UTF-8 encoding |
ContentMessage
Customers can also compose a raw RCS text message using the contentMessage parameter as shown in the example below:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer {TOKEN} \
-H 'Content-Type: application/json' \
-d '{
"from": "gtz9wXVkA51HSyB5wYTcP","to": "+14086270435","body":"{\"contentMessage\":{\"text\":\"Hello, this is my first RCS message!\"}"
}
Media
The media type further defines an RCS media message. For example, the RCS message might be a JPEG linked to a website.
It's best practice to set contentMessage.forceRefresh to false. Setting contentMessage.forceRefresh to true forces the System to fetch new content from the specified URL, even if the URL content is cached, which increases message delivery times for users.
Note: To send message in raw RCS format, please set the Content_type parameter as below.
{“content_type":"application/vnd.scg.grcs.raw-message”}
|
Parameter |
Description |
|
fileUrl |
Link to a publicly reachable URL of a media file. The full path must be used. The URL must use https:// and must link to a media file in. 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. |
|
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:
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages
-H 'Authorization: Bearer [TOKEN} \
-H 'Content-Type: application/json' \
-d '{
"from": "gtz9wXVkA51HSyB5wYTcP",
"to": ["+18131234567"],
"content_type": "application/vnd.scg.grcs.raw-message",
"body":""{
'contentMessage': {
'contentInfo': {
'fileUrl': 'http://www.google.com/logos/doodles/2015/googles-new-logo-5078286822539264.3-hp2x.gif',
'forceRefresh': false
}
}
}"
Suggestion
A suggested reply or a suggested action included within a rich card or within a suggestion chip list.
|
Parameter |
Description |
|
reply |
SuggestedReply: User can tap a suggested reply to send the text reply back to the application, chatbot or agent Type: String
|
|
action
|
SuggestedAction: User can tap a suggested reply to initiate a corresponding native action on a device
The native action initiated on the device when the user taps the suggested action action can be only one of the following:
Additional fields:
Additional Fields:
|
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.
Rich cards can contain the following items:
- Image/video
- Title text
- Description text
- A list of suggested replies and suggested actions (maximum 4)
|
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:
Cards expand vertically to fit their contents. Rich cards have a minimum height of 112 DP and a maximum height of 344 DP. If the contents of a card are not large enough to fill the minimum card height, the card expands and fills the extra height with white space |
|
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 below for more info Note: There must be at least one card in this array. Type: card Required: Yes |
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: No. However, if used, you must use UTF-8 encoding. The maximum size of the title should be no more than 4096 bytes. |
|
description
|
Descriptive text that appears on the card. Type: string Required: At least one of description, media, or suggestions is required, but any combination of these three is valid. |
|
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. Type: object Required: At least one of description, media, or suggestions 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: At least one of description, media, or suggestions is required. Any combination of these three is valid; however, the maximum number of suggestions for a single richCard is 4 — for example, this might have three replies, three actions, or two actions and one suggestion. A maximum of 2 suggestions is allowed for each card in a carousel. See "cardHeight" below for information about carousel cards. |
Media
media defines the card associated with the Rich Card. This might include displaying the Rich Card with a graphic.
|
Parameter |
Description |
|
fileUrl |
Publicly reachable link to a media file. The full path must be used. The URL must use https:// and must link to a media file. 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 Publicly reachable URL to the image and video thumbnails only, if a thumbnail is used. The full path must be used, starting with https://. Type: string Required: No |
|
thumbnailImageAlignment |
The image mime type. For example, this might be image/jpeg. Type: string Required: No |
|
thumbnailMimeType |
The image mime type. For example, this might be image/jpeg. Type: string |
|
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 |
| 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. |
-d "{
'contentMessage': {
'richCard': {
'carouselCard': {
'cardWidth':'MEDIUM',
'cardContents': [
{
'title':'Card #1',
'description':'The description for card #1',
'suggestions': [
{
'reply': {
'text':'Card #1',
'postbackData':'card_1'
}
}
],
'media': {
'height':'MEDIUM',
'contentInfo': {
'fileUrl':'https://storage.googleapis.com/kitchen-sink-sample-images/cute-dog.jpg',
'forceRefresh':false
}
}
},
{
'title':'Card #2',
'description':'The description for card #2',
'suggestions': [
{
'reply': {
'text':'Card #2',
'postbackData':'card_2'
}
}
],
'media': {
'height':'MEDIUM',
'contentInfo': {
'fileUrl':'https://storage.googleapis.com/kitchen-sink-sample-images/elephant.jpg',
'forceRefresh':false
}
}
}
]
}
}
}
}"
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. Type: object Required: A suggestion must have either an action or a reply, but at least one. |
|
reply
|
Defines the reply. See reply below for more information. Type: object Required: A suggestion must have either an action or a reply, but at least one. |
Example usage
-d "{
'contentMessage': {
'text': 'Hello, world!',
'suggestions': [
{
reply: {
'text': 'Suggestion #1',
'postbackData': 'suggestion_1',
},
},
{
reply: {
'text': 'Suggestion #2',
'postbackData': 'suggestion_2',
},
}
]
}
}"
reply
A reply prompts the recipient with display text to perform the requested suggestion.
|
Parameter |
Description |
|
Text |
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. |
|
postbackData |
When passed in a request, this parameter allows information about the tapped reply to be returned to you as an MO event that the specific reply was tapped. This MO event can include additional information about the customer, such as a Phone number. 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,"postbackData:" { \"phoneNumber\":\"14085551234\"}". Required: No. However, if this parameter is not passed no information is returned to you. |
Example usage
{
reply: {
'text': 'Call',
'postbackData': 'suggestion_1',
},
action
Defines the action to take when the user clicks a media type if an action is defined for suggestions.
|
Parameter |
Description |
|
Text |
Displays the text the recipient sees for that action. For example, this might be "Contact 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. |
|
postbackData |
When passed in a request, this parameter allows information about the tapped action to be returned to you as an MO event that the specific action was tapped. This MO event 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, \"postbackData\":"{\"Checkthisout!\"}". Required: No. However, if this parameter is not passed no information is returned to you. |
Example usage
-d "{
'contentMessage': {
'text': 'Hello, world!',
'suggestions': [
{
'action': {
'text': 'Call',
'postbackData': 'postback_data_1234',
'dialAction': {
'phoneNumber': '+15556667777'
}
}
}
]
}
}"
Example: shareLocationAction
curl -L -X POST 'https://api.syniverse.com/scg-external-api/api/v1/messaging/messages' -H 'Content-Type: application/json' -H 'Authorization: Bearer Token' --data-raw '{
"from": "gtz9wXVkA51HSyB5guip",
"to": "+14085551212",
"content_type": "application/vnd.scg.grcs.raw-message",
"body": "{\"contentMessage\":{\"text\":\"Where are you located, do you want to share your location?\",\"suggestions\":[{\"action\":{\"shareLocationAction\":{},\"text\":\"Share location\",\"postbackData\":\"See my Location\"}},{\"reply\":{\"text\":\"No\",\"postbackData\":\"No\"}},]}}"
}'
Usage Example with Combination of Contents
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
"from": "SilzjFK6CBBmgFUBaYVWJ",
"to": "+14085551222",
"content_type": "application/vnd.scg.grcs.raw-message",
"body":"{\"contentMessage\":{\"richCard\":{\"standaloneCard\":{\"cardOrientation\":\"VERTICAL\",\"thumbnailImageAlignment\":\"LEFT\",\"cardContent\":{\"suggestions\":[{\"reply\":{\"text\":\"More info\",\"postbackData\":\"replied-more-info\"}},{\"reply\":{\"text\":\"Sign me Up!\",\"postbackData\":\"replied-Sign-me-up\"}},{\"action\":{\"text\":\"Visit Barcelona\",\"postbackData\":\"action-openurl\",\"openUrlAction\":{\"url\":\"https://www.barcelona.com/barcelona_city_guide\"}}},{\"action\":{\"text\":\"View direction\",\"postbackData\":\"location\",\"viewLocationAction\":{\"latLong\":{\"latitude\":\"37.2779914\",\"longitude\":\"-121.8890323\"},\"label\":\"Optima Dental\"}}}],\"title\":\"Barcelona in the Summer!!\",\"description\":\" Visiting Barcelona? Book the best tours and activities for the best price! Incredible experiences. Flexible booking. Over 40,000 activities. Easy online booking. Easy price comparison. No cancellation fees. Top attraction tickets. \n \n Plan your trip \",\"media\":{\"height\":\"MEDIUM\",\"contentInfo\":{\"fileUrl\":\"https://www.ciee.org/sites/default/files/content/program/main-image/hero_spain_barcelona_1600x1000_02_0_0.jpg\"}}}}}}}"
}'
SMS Fallback
When used, the Failover parameter sends a fallback SMS message in the event the end user's phone does not support RCS. You must be provisioned to use this account and have a private channel created. For more information on Private channel, visit our knowledge base.
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 will be split into multiple fragments using the SCG Messaging API. Your carrier may charge you for each sent fragment.
Please note that you currently trigger a fallback to SMS automatically for a RCS RICH CARD or Rich media message.
Sample
curl -X POST \
https://api.syniverse.com/scg-external-api/api/v1/messaging/messages \
-H 'Authorization: Bearer Token \
-H 'Content-Type: application/json' \
-d '{
"from": "channel:leMXuQrmJ3dcR2OE7q4BV2",
"to": "18005551212",
"failover": "SMS",
"contact_delivery_address_priority": ["RCS"],
"sender_id_sort_criteria": ["DELIVERY_ADDRESS"],
"body": "fallback to NON rcs capable device"
}
ESS Events and MO content type changes
New topic added - “SCG-Chat”.
New event in added in topic “SCG-Chat” - “typing”. The event indicates that the remote party is typing within the chat window of the RCS agent represented by the corresponding sender id.
{"evt-tp":"typing","fld-val-list":{"sender_id_alias":"XlmTargEIStVGU4kXlDFQ6","sender_id_id":"XlmTargEIStVGU4kXlDFQ6","company_id":99999,"to_address":"+359886178558@softaval-rcs-project-for-scg.iam.gserviceaccount.com","from_address":"+359888121204","application_id":536,"timestamp":"2018-12-20T17:12:03.281987Z"}}
Content Type "application/vnd.scg.location"
This new content type defined for MO message and events indicate that the body of the message contains location coordinates following this example:
"longitude: 23.3891704, latitude: 42.6561869"
ShareLocation Sample Event
{
"topic": "SCG-Message",
"attempt": 1,
"event": {
"fld-val-list": {
"sender_id_alias": "Kolanator",
"mo_price": 0.0025,
"company-id": 0000,
"sender_id_id": "gtz9wXVkA51HSyB5quip",
"message_body": "longitude: 23.3891704, latitude: 42.6561869",
"message_id": "MsHkN654PDQL2hmA5NbcmiSg_RCS",
"to_address": "716xxxxxxxxx",
"has_attachment": false,
"from_address": "+14085551212",
"application_id": 4334,
"message_body_content_type": "application/vnd.scg.location"
},
"evt-tp": "mo_message_received",
"timestamp": "2020-07-16T18:44:20.182Z"
},
"event-id": "ifG8Fw52QMSM-PuACti1bw"
}
Content Type "application/vnd.scg.grcs.suggestion-response"
This new content type defined for MO message and events indicate that the body of the message contains stringified JSON of the RCS specific suggestion response, like this:
"{\"postbackData\":\"replied-no-no\",\"text\":\"no, no, thanks\"}"
Parsed as JSON this will render the reply chosen by the user and the corresponding postback data associated with this reply in the suggestions section of the MT message.
0 Comments