RCS
Signing Up
RCS (Rich Communication Services) is a protocol for sending multimedia messages to your customers using the Android OS via an agent dedicated to your brand or company.
The use of these APIs is conditional on two elements:
The opening of an agent with French metropolitan operators. To do this, you need to fill in the form available here. Once completed, the form must be returned with the required graphics to support@mtarget.fr and csm@mtarget.fr with the subject line "Opening of an RCS AGENT".
Opening an account to test our service. Creating an account is free and without obligation. To open an account, send an e-mail to support@mtarget.fr and csm@mtarget.fr with the subject "Creation of an API RCS account" and specifying your contact details:
- Your details:
- email account
- first name
- last name
- company name
- phone number
we will create an account for you and provide you with the credentials necessary to use our API.
The account that we are opening for you can support several different offers and prices depending on the destinations and operators, so please tell us which destinations you want to test.
Simplified query
This query is based on our API for sending SMS with the addition of an agentMessage parameter, the content of which will be described in the Components section.
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{"contentMessage": [{ "example" : "value"}]}This parameter must always contain a contentMessage object.
Components
RCS allows you to send complex messages that are no longer just text. For this, it will be necessary to respect the precise syntax of a JSON object which will be described below.
Simple text
This method allows you to send a message containing only text. We get a "classic" SMS rendering with the image chosen by you when creating the agent in the small bubble:
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{"contentMessage": {"text": "Du texte simple, mais sans les limitations habituelles des SMS ! 🥳 On peut envoyer des messages longs (jusqu'à 3072 caractères), des caractères spéciaux par défaut (on n'est plus limité à l'alphabet GSM et ses 136 glyphes), et des émojis 👍"}}In the JSON, the text parameter is filled in and can contain special characters and emojis up to 3072 characters
Simple File
This will return you a result like below:
The recommended image ratios are:
- Vertical map: 2: 1, 16: 9, 7: 3 (in pixels: 1440x720, 1440x810, 1440x617)
- Horizontal map: 3: 4 (in pixels: 768 * 1024)
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{"contentMessage": {"contentInfo": {"fileUrl": "https://yourpublicimage.jpg"}}}In the JSON, the contentInfo object is appended containing the fileUrl parameter which should point to a publicly accessible file.
Rich Card Only
This will give you a result like below :
or
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{ "contentMessage" : { "richCard" : { "standaloneCard" : { "cardOrientation" : "VERTICAL", "cardContent" : { "title" : "Port Vauban à Antibes", "description" : "Une image récupérée sur Wikimedia Commons.", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage.jpg" } } } } } }}This JSON is explained in the next part.
Rich Card Only JSON
Here, the contentMessage contains the richCard element which itself contains the standaloneCard object. This object contains properties related to the global object such as its orientation. It also contains the card itself cardContent which describes its title, description and image (in the media object).
Vertical Rich Card
{ "contentMessage" : { "richCard" : { "standaloneCard" : { "cardOrientation" : "VERTICAL", "cardContent" : { "title" : "Port Vauban à Antibes", "description" : "Une image récupérée sur Wikimedia Commons.", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage.jpg" } } } } } } }
Horizontal Rich Card
{ "contentMessage" : { "richCard" : { "standaloneCard" : { "cardOrientation" : "HORIZONTAL", "thumbnailImageAlignment" : "RIGHT", "cardContent" : { "title" : "Port Vauban à Antibes", "description" : "Une image récupérée sur Wikimedia Commons.", "media" : { "contentInfo" : { "fileUrl" : "https://yourpublicimage.jpg" } } } } } } }
Rich Cards Carousel
This will give you a result like below:
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{ "contentMessage" : { "richCard" : { "carouselCard" : { "cardWidth" : "MEDIUM", "cardContents" : [{ "title" : "Encore", "description" : "Avec", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage1.jpg" } } },{ "title" : "des", "description" : "des", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage2.jpg" } } }] } } }}This JSON is explained in the next part.
Rich Cards Carousel JSON
Here, the contentMessage contains the richCard element which itself contains the carouselCard object. This object contains the property of the witdh of cards, cardWidth ,which can only take as a value SMALL or MEDIUM. It also contains a cardContents array (note the S) which therefore contains cardContent elements that describe the titles, descriptions and images found in the carousel.
{ "contentMessage" : { "richCard" : { "carouselCard" : { "cardWidth" : "MEDIUM", "cardContents" : [ { "title" : "Encore", "description" : "avec", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage1.jpg" } } }, { "title" : "des", "description" : "des", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage2.jpg" } } }, { "title" : "tests", "description" : "images", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://yourpublicimage3.jpg" } } } ] } } } }
Suggestions
This will give you a result like below:
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8
usernameUSERNAME
Your username as provided on sign up
passwordPASSWORDYour password as provided on sign up
msisdnMSISDNRecipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3
msgWhateverThis parameter is mandatory but not used if the agentMessage parameter is entered
agentmessage{ "contentMessage" : { "text" : "Hey, voici quelques suggestions ⬇", "suggestions" : [ { "reply" : { "text" : "Coucou", "postbackData" : "user_clicked_coucou" } }, { "action" : { "text" : "Appeler !", "postbackData" : "user_clicked_appeler", "dialAction" : { "phoneNumber" : "+33561251255" } } }, { "action" : { "text" : "Trouver MTarget", "postbackData" : "user_clicked_trouver_mtarget", "viewLocationAction" : { "latLong" : { "latitude" : 43.550808, "longitude" : 1.501273 }, "label" : "MTarget" } } }, { "action" : { "text" : "Ajouter au calendrier", "postbackData" : "user_clicked_ajouter_au_calendrier", "createCalendarEventAction" : { "startTime" : "2019-09-02T08:00:00+02:00", "endTime" : "2019-09-02T18:00:00+02:00", "title" : "Rentrée scolaire !", "description" : "Je savais pas quoi mettre comme événement" } } }, { "action" : { "text" : "Visiter le site", "postbackData" : "user_clicked_visiter_le_site", "openUrlAction" : { "url" : "https://www.mtarget.fr/" } } }, { "action" : { "text" : "Se renseigner en vidéo", "postbackData" : "user_clicked_se_renseigner_en_video", "openUrlAction" : { "url" : "https://youtu.be/_LXxFAo6sLY" } } } ] }}This JSON is explained in the next part.
Suggestions JSON
Here, the contentMessage finds a text value and bubbles are displayed below the messages. These bubbles are different actions defined below.
{ "contentMessage" : { "text" : "Hey, voici quelques suggestions ⬇", "suggestions" : [
{ "reply" : { "text" : "Coucou", "postbackData" : "user_clicked_coucou" } },
{ "action" : { "text" : "Appeler !", "postbackData" : "user_clicked_appeler", "dialAction" : { "phoneNumber" : "+33561251255" } } },
{ "action" : { "text" : "Trouver MTarget", "postbackData" : "user_clicked_trouver_mtarget", "viewLocationAction" : { "latLong" : { "latitude" : 43.550808, "longitude" : 1.501273 }, "label" : "MTarget" } } },
{ "action" : { "text" : "Ajouter au calendrier", "postbackData" : "user_clicked_ajouter_au_calendrier", "createCalendarEventAction" : { "startTime" : "2019-09-02T08:00:00+02:00", "endTime" : "2019-09-02T18:00:00+02:00", "title" : "Rentrée scolaire !", "description" : "Je savais pas quoi mettre comme événement" } } },
{ "action" : { "text" : "Visiter le site", "postbackData" : "user_clicked_visiter_le_site", "openUrlAction" : { "url" : "https://www.mtarget.fr/" } } },
{ "action" : { "text" : "Se renseigner en vidéo", "postbackData" : "user_clicked_se_renseigner_en_video", "openUrlAction" : { "url" : "https://youtu.be/_LXxFAo6sLY" } } }
] } }
Suggestions and carousel
You can add a suggestion to cards in carousels as follows:
{ "contentMessage" : { "richCard" : { "carouselCard" : { "cardWidth" : "MEDIUM", "cardContents" : [ { "title" : "Réponse simple", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://dl.mtarget.fr/MTG/logo-original-M-target_fond-fonce.png" } }, "suggestions" : [ { "reply" : { "text" : "Coucou", "postbackData" : "user_clicked_coucou" } } ] }, { "title" : "Téléphoner", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://dl.mtarget.fr/MTG/logo-original-M-target_fond-fonce.png" } }, "suggestions" : [ { "action" : { "text" : "Appeler !", "postbackData" : "user_clicked_appeler", "dialAction" : { "phoneNumber" : "+33561251255" } } } ] }, { "title" : "Événement", "media" : { "height" : "MEDIUM", "contentInfo" : { "fileUrl" : "https://dl.mtarget.fr/MTG/logo-original-M-target_fond-fonce.png" } }, "suggestions" : [ { "action" : { "text" : "Ajouter au calendrier", "postbackData" : "user_clicked_ajouter_au_calendrier", "createCalendarEventAction" : { "startTime" : "2019-09-02T08:00:00+02:00", "endTime" : "2019-09-02T18:00:00+02:00", "title" : "Rentrée scolaire !", "description" : "Je savais pas quoi mettre comme événement" } } } ] } ] } } } }
At the end, you get a result similar to:
Charset in the header
Be careful to keep the charset used (in our examples, utf-8) in your Content-Type header , in your own tool. Without this header, our API misinterprets the content of the agentmessage (we are dealing with the iso 8859-1 by default for legacy reasons).