RCS

Find out more about the features and specifics of RCS solution.

In the following examples, we'll show you how to use RCS solution for sending text, file, card and carousel type of messages.

Structure of each message will be covered as well as supported types of media which can be used in communication.

Furthermore, everything about incoming messages will be cover as well.

  1. Sending RCS text messages
  2. Sending RCS rich messages
  3. Delivery and Seen Reports
  4. Incoming RCS messages
  5. Supported Media Types

Sending RCS text messages

For sending RCS messages, you can use the advanced API method. Parameters that should be set in the request body are destination and message. The message could be text, file, card or carousel (examples are given below). Structure of each type varies, detail explanation between types is given further in the document. 

 

Property name Type Description
type constant Message type, describing type of message which is going to be sent over RCS. In case of Text message, value must be "TEXT".
text string Text of the message that will be sent. Max 1000 characters.

 

Request Example:

  • JSON
POST /ott/rcs/1/message HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json

{
	"to": "385977666618",
	"message": {
		"type": "TEXT",
		"text": "Hello world!"
	}
}

Response: 

  • JSON
{  
   "messages":[  
      {  
         "to":"385977666618",
         "messageCount":1,
         "messageId":"11c6f19b-61bb-42a6-9e1b-0415a69b0ba0",
         "status":{  
            "groupId":1,
            "groupName":"PENDING",
            "id":7,
            "name":"PENDING_ENROUTE",
            "description":"Message sent to next instance"
         }
      }
   ]
}

Sending RCS Rich messages

Following examples are given to demonstrate how to send different type of RCS messages. In RCS solution every outgoing message is defined by it's type, and multiple fields contained in message object:

  • JSON
{
	"to": "{{destination}}",
	"message": {
		"type": "{{type}}",
    /*
    	Fields specific for certain message type
    */
	}
}

Further in text structure of message object, defined in the request body, will be described in details (fields, fields types, constraints, etc.)

Text message with suggestions

Property name Type Description
type constant Message type, describing the type of message which is going to be sent over RCS. In the case of Text message, the value must be "TEXT".
text string Text of the message that will be sent. Max 1000 characters.
suggestions array of suggestions Suggestions which can be sent with the text message. Suggestions are not required field, but the user can not send more than 10 suggestion within the message.

 

Request Example:

  • JSON
{
	"to": "385977666618",
	"message": {
		"type": "TEXT",
		"text": "Pick one!",
		"suggestions": [
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			},
			{
				"type": "OPEN_URL",
				"text": "Open URL",
				"postbackData": "OPEN_URL",
				"url": "https://www.infobip.com"
			},
			{
				"type": "DIAL_PHONE",
				"text": "Dial phone",
				"postbackData": "DIAL_PHONE",
				"phoneNumber": "+{{destination}}"
			},
			{
				"type": "SHOW_LOCATION",
				"text": "Open map",
				"postbackData": "OPEN_MAP",
				"latitude": 45.793418,
				"longitude": 15.946297
			},
			{
				"type": "REQUEST_LOCATION",
				"text": "Share location",
				"postbackData": "REQUEST_LOCATION"
			}
		]
	}
}

File message

File RCS Message structure is used for sending files over RCS. Structure of the body for successful file sending through RCS is given in the table below.

 

Property name Type Description
type constant Message type, describing the type of message which is going to be sent over RCS. In the case of File message, the value must be "FILE".
file resource object Resource object describing file which is going to be sent over RCS.
thumbnail resource object Resource object describing thumbnail which is going to be sent over RCS.
suggestions array of Suggestion Objects Suggestions which can be sent with file message. Suggestions are not required field, but the user can not send more than 10 suggestion within the message.

 

Request Example:

  • JSON
{
	"to": "385977666618",
	"message": {
		"type": "FILE",
		"file": {
			"url": "https://www.infobip.com/infobip-logo.png"
		},
		"thumbnail": {
			"url": "https://www.infobip.com/infobip-logo.png"
		},
		"suggestions": [
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			},
			{
				"type": "OPEN_URL",
				"text": "Open URL",
				"postbackData": "OPEN_URL",
				"url": "https://www.infobip.com"
			},
			{
				"type": "DIAL_PHONE",
				"text": "Dial phone",
				"postbackData": "DIAL_PHONE",
				"phoneNumber": "+{{destination}}"
			},
			{
				"type": "SHOW_LOCATION",
				"text": "Open map",
				"postbackData": "OPEN_MAP",
				"latitude": 45.793418,
				"longitude": 15.946297
			},
			{
				"type": "REQUEST_LOCATION",
				"text": "Share location",
				"postbackData": "REQUEST_LOCATION"
			},
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			}
		]
	}
}

Card Message

Card RCS Message structure is used for sending cards messages over RCS. 

 

Property name Type Description
type constant Message type, describing the type of message which is going to be sent over RCS. In the case of Card message, the value must be "CARD".
orientation string Orientation type. Can be "HORIZONTAL" or "VERTICAL". Orientation type defines orientation in Card message which is going to be sent over RCS.
alignment string Alignment type. Can be "LEFT" or "RIGHT". Alignment type defines alignment in Card message which is going to be sent over RCS.
content CardContent object CardContent object which will be sent in the message.
suggestions Array of Suggestions List of suggestions which will be sent in the message. Suggestions are not required field, but the user can not send more than 10 suggestion within the message.

 

Request example:

  • JSON
{
	"to": "385977666618",
	"message": {
		"type": "CARD",
		"orientation": "VERTICAL",
		"alignment": "LEFT",
		"content": {
			"title": "Card title",
			"description": "Some supercool, attention-grabbing description",
			"media": {
				"height": "TALL",
				"file": {
					"url": "https://www.infobip.com/infobip-logo.png"
				}
			},
		"suggestions": [
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			},
			{
				"type": "OPEN_URL",
				"text": "Open URL",
				"postbackData": "OPEN_URL",
				"url": "https://www.infobip.com"
			}
		]
		},
		"suggestions": [
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			},
			{
				"type": "OPEN_URL",
				"text": "Open URL",
				"postbackData": "OPEN_URL",
				"url": "https://www.infobip.com"
			},
			{
				"type": "DIAL_PHONE",
				"text": "Dial phone",
				"postbackData": "DIAL_PHONE",
				"phoneNumber": "+385977666618"
			},
			{
				"type": "SHOW_LOCATION",
				"text": "Open map",
				"postbackData": "OPEN_MAP",
				"latitude": 45.793418,
				"longitude": 15.946297
			},
			{
				"type": "REQUEST_LOCATION",
				"text": "Share location",
				"postbackData": "REQUEST_LOCATION"
			},
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			}
		]
		
	}
}

CardContent

Property name Type Description
title string Title , defines the title of Card which is going to be sent over RCS. Minimum length of a string is 1 and the maximum length is 200.
description string The description defines description of Card which is going to be sent over RCS. Minimum length of a string is 1 and the maximum length is 200.
media CardMedia Object CardMedia Object which is going to be sent as RCS message.
suggestions Array of Suggestion Objects Suggestions which can be sent with the text message. Suggestions are not required field, but the user can not send more than 4 suggestion within CardContent.

 

CardMedia

Property name Type Description
file Resource Object File which is going to be send in CardMedia.
thumbnail Resource Object Thumbnail which is going to be send in CardMedia.
height Height enum Height enum of CardMedia Height.

Carousel message

Carousel RCS Message structure is used for sending cards messages over RCS. 

Property name Type Description
type string Message type, describing the type of message which is going to be sent over RCS. In the case of Carousel message, the value must be "CAROUSEL".
cardWidth string With type. Can be "SMALL" or "MEDIUM". Width type defines width of Carousel message which is going to be sent over RCS.
contents CardMedia Object The array of CardContent object which will be sent in the message. Min 2
suggestions Array of Suggestion Objects List of suggestions which will be sent in the message. Suggestions are not required field, but the user can not send more than 10 suggestion within the message.

 

Request example:

  • JSON
{
  "to": "385977666618",
  "message": {
    "type": "CAROUSEL",
    "cardWidth": "MEDIUM",
    "contents": [
      {
        "title": "Card title",
        "description": "Some supercool, attention-grabbing description",
        "media": {
          "height": "TALL",
	      "file": {
	        "url": "https://www.infobip.com/infobip-logo.png"
          }
        }
      },
      {
        "title": "Card title",
        "description": "Some supercool, attention-grabbing description",
        "media": {
          "height": "TALL",
          "file": {
            "url": "https://www.infobip.com/infobip-logo.png"
          }
        }
      }
    ],
    "suggestions": [
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			},
			{
				"type": "OPEN_URL",
				"text": "Open URL",
				"postbackData": "OPEN_URL",
				"url": "https://www.infobip.com"
			},
			{
				"type": "DIAL_PHONE",
				"text": "Dial phone",
				"postbackData": "DIAL_PHONE",
				"phoneNumber": "385977666618"
			},
			{
				"type": "SHOW_LOCATION",
				"text": "Open map",
				"postbackData": "OPEN_MAP",
				"latitude": 45.793418,
				"longitude": 15.946297
			},
			{
				"type": "REQUEST_LOCATION",
				"text": "Share location",
				"postbackData": "REQUEST_LOCATION"
			},
			{
				"type": "REPLY",
				"text": "Reply",
				"postbackData": "REPLY"
			}
		]
  }
}

Suggestion

Suggestions can be sent with multiple messages type. Suggestions can be of different type. Each suggestion come with Type field which describes type of suggestions. Structure of suggestions are described in table below:

 

Property name Type Description
type string Suggestion type. Can be "REPLY", "OPEN_URL", "DIAL_PHONE", "SHOW_LOCATION" or "REQUEST_LOCATION".
text string Suggestion text. Maximum number of characters: 25.
postbackData string String which is going to be sent as a reply to a suggestion. Maximum number of character: 2048.

 

 

ReplySuggestion

Property name Type Description
type string   Defines the type of Reply Suggestion. For ReplySuggestion value is "REPLY".
text string Suggestion text, in a message which is going to be sent over RCS, a suggestion will be displayed under a given text. The maximum number of characters: 25.
postbackData string String which is going to be sent as a reply to a suggestion. Maximum number of character: 2048.

 

OpenUrlSuggestion

Property name Type Description
type string   Defines the type of Reply Suggestion. For OpenUrlSuggestion value is "OPEN_URL"
text string Suggestion text, in a message which is going to be sent over RCS, a suggestion will be displayed under a given text. The maximum number of characters: 25.
postbackData string String which is going to be sent as a reply to a suggestion. The maximum number of character: 2048.
url string URL. Must be a valid one.

 

DialPhoneSuggestion

Property name Type Description
type string  Defines the type of Reply Suggestion. For DialPhoneSuggestion value is "DIAL_PHONE"
text string Suggestion text, in a message which is going to be sent over RCS, a suggestion will be displayed under a given text. The maximum number of characters: 25.
postbackData string String which is going to be sent as a reply to a suggestion. The maximum number of character: 2048.
phoneNumber string Valid phone number. Must satisfy regex: "\\+\\d{5,15}"

 

ShowLocationSuggestion

Property name Type Description
type string For ShowLocationSuggestion value is "SHOW_LOCATION"
text string Suggestion text, in a message which is going to be sent over RCS, a suggestion will be displayed under a given text. The maximum number of characters: 25.
postbackData string String which is going to be sent as a reply to a suggestion. The maximum number of character: 2048.
latitude double   Latitude. Value must be between -90 and 90.
longitude double Longitude. Value must be between -180 and 180.
label string Label of the location. Up to 100 characters.

 

RequestLocationSuggestion

Property name Type Description
type string   For RequestLocationSuggestion value is "REQUEST_LOCATION"
text string Suggestion text, in a message which is going to be sent over RCS, a suggestion will be displayed under a given text. Maximum number of characters : 25.
postbackData string String which is going to be sent as a reply to a suggestion. Maximum number of character: 2048.

Resource

The resource can be sent with multiple messages type. Structure of resource are described in the table below:

 

Property name Type Description
url string URL of the given resource. Must be a valid resource and not longer than 1000 characters.

Delivery and Seen Reports

Delivery Reports

Once you’ve successfully sent your message, a delivery report will be sent back on successfully message delivery. Here is an example of a delivery report:

  • JSON
{  
   "results":[  
      {  
         "bulkId":"",
         "price":{  
            "pricePerMessage":0.000000,
            "currency":"UNKNOWN"
         },
         "status":{  
            "id":5,
            "groupId":3,
            "groupName":"DELIVERED",
            "name":"DELIVERED_TO_HANDSET",
            "description":"Message delivered to handset"
         },
         "error":{  
            "id":0,
            "name":"NO_ERROR",
            "description":"No Error",
            "groupId":0,
            "groupName":"OK",
            "permanent":false
         },
         "messageId":"6051785f-c0d0-4e2a-8953-069eb1e126d5",
         "doneAt":"2019-07-23T11:58:48.089+0000",
         "messageCount":1,
         "sentAt":"2019-07-23T11:58:45.539+0000",
         "to":"385977666618",
         "channel":""
      }
   ]
}

Seen Reports

Example for the seen report is given in the example below:

  • JSON
{  
   "results":[  
      {  
         "messageId":"179072311174543319",
         "to":"385977666618",
         "sentAt":"2019-07-23T13:17:45.432+0200",
         "seenAt":"2019-07-23T13:17:47.000+0200"
      }
   ]
}

Incoming RCS messages

In RCS solution every incoming message is defined by its type, and multiple fields contained in the message object. Each incoming message is mapped in internal structure described in subchapters:

Incoming Text Message

The text Message structure is used when user wants to send RCS message which is of type TEXT. In case that end user is sending text message, message will be represented ins structure given below:

 

Property name Type Description
type constant For Text Message value is "TEXT"
text string The text which is sent in an incoming message.

 

JSON example

  • JSON
{  
   "results":[  
      {  
         "from":"385992691430",
         "to":"infobip",
         "integrationType":"RCS",
         "receivedAt":"2019-08-02T11:20:05.863+0000",
         "messageId":"Ms=F11DR9CQIKqAkV4fGTuNw",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{  
            "text":"Hi",
            "type":"TEXT"
         },
         "price":{  
            "pricePerMessage":0.000000,
            "currency":"HRK"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":2139
}

Incoming File Message

The file Message structure is used in case of sending the file as an incoming message. Using RCS end user can send file as incoming message. All data which are needed to represent incoming file (url, name, ContentType) will represented as structure described below:

 

Property name Type Description
type constant    For File Message value is "FILE"
url string url of an file which is sent in an incoming message.
name string name of a file which is sent in an incoming message.
contentType string contentType of a file which is sent in an incoming message.
size long size of the file which is sent in an incoming message. Minimum value is 0. Size of file is considered to be expressed in bytes.

 

JSON example

  • JSON
{  
   "results":[  
      {  
         "from":"385977666618",
         "to":"infobip",
         "integrationType":"RCS",
         "receivedAt":"2019-08-02T11:02:21.857+0000",
         "messageId":"MsXXWjWPSqRJ2ufXGXeqpkiA",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{  
            "url":"https://rcs-user-content-us.storage.googleapis.com/7785f541-3070-43f6-8842-80b02c479e2e/795a531f4ddcf89e8ebd638d5a47ab9ffc07572c873ee2a3ce663a1c3615",
            "name":"acc=1;doc=encoded=cCEKZcDa1WOdPEhTLxVbFFEpwfmXj4SacCDzbNXslu7KniqM0gatRrc=.jpg",
            "contentType":"image/jpeg",
            "size":581699,
            "type":"FILE"
         },
         "price":{  
            "pricePerMessage":0.000000,
            "currency":"HRK"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":2137
}

Location Message

The Location Message structure is used in case of sending location as an incoming message. Using RCS end user can send location as incoming message. Coordinates of location (latitude and longitude) will be represented as structure given below: 

 

Property name Type Description
type constant For Location Message value is "LOCATION"
latitude double Latitude. The value must be between -180 and 180.
longitude double Longitude. The value must be between -90 and 90.

 

JSON example

  • JSON
{  
   "results":[  
      {  
         "from":"385992691430",
         "to":"infobip",
         "integrationType":"RCS",
         "receivedAt":"2019-08-02T11:24:37.366+0000",
         "messageId":"Ms1lZn9YC7Q1WnPzZgCD4bMA",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{  
            "latitude":45.7935134,
            "longitude":15.9461141,
            "type":"LOCATION"
         },
         "price":{  
            "pricePerMessage":0.000000,
            "currency":"HRK"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":2139
}

Suggestion Message

The Suggestion Message structure is used in case of sending suggestion answer as an incoming message. RCS support sending suggestions messages to end users. In case when end user receives message which contains suggestions, end user can choose one of suggestion and instantly reply to message. Choice of end user (incoming message) will represented as structure described below:

 

Property name Type Description
type constant For Suggestion Message value is "SUGGESTION"
text string text of incoming suggestion.
postbackData string postbackData of incoming suggestion

 

JSON example

  • JSON
{  
   "results":[  
      {  
         "from":"385992691430",
         "to":"infobip",
         "integrationType":"RCS",
         "receivedAt":"2019-08-02T11:26:59.153+0000",
         "messageId":"MsxKluA1JkQvOXtedW8cOw6g",
         "pairedMessageId":null,
         "callbackData":null,
         "message":{  
            "text":"Reply",
            "postbackData":"REPLY",
            "type":"SUGGESTION"
         },
         "price":{  
            "pricePerMessage":0.000000,
            "currency":"HRK"
         }
      }
   ],
   "messageCount":1,
   "pendingMessageCount":2139
}

Supported Media Types

Supported Media Types are given in the table below:

 

Media Type Extensions Description
Image .jpg
.png		 Supported media types for managing images.
Audio   Google does not support audio formats.
Video .mp4 Supported media types for managing videos.