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.

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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:

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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)

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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 :

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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" } 
          } 
        } 
      } 
    } 
  } 
}

cardOrientation defined where the text will be relative to the image. Here, "VERTICAL" means the text will be under the image. When this parameter is used, you also need to give the height of the image which needs to be SHORT/MEDIUM/TALL.

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" } 
          } 
        } 
      } 
    } 
  } 
}

cardOrientation defined where the text will be relative to the image. Here, "HORIZONTAL" means the text will be to the left or the the right of the image. When this parameter is used, you also need to give the thumbnailImageAlignment to the object standaloneCard which needs to be LEFT/RIGHT.

Rich Cards Carousel

This will give you a result like below:

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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:

POST https://api-public-2.mtarget.fr/messages HEADERS

Content-Typeapplication/x-www-form-urlencoded;charset=utf-8

BODY

usernameUSERNAME

Your username as provided on sign up

passwordPASSWORD

Your password as provided on sign up

msisdnMSISDN

Recipient number with area code (+33 ...) or in international format (0033 ...). You can add up to 500 msisdns separated by a comma: + 336xxxx1, + 336xxxx2, + 336xxxx3

msgWhatever

This 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"
          }
        },

A simple message which will be send by the user as if he typed it! Please see that it is not an object action but a reply.

        {
          "action" : {
            "text" : "Appeler !",
            "postbackData" : "user_clicked_appeler",
            "dialAction" : {
              "phoneNumber" : "+33561251255"
            }
          }
        },

The object action has a text which appears in the bubble, a postbackData which will be returned in the MO and a dialAction which identifies the action as a call (by giving it is parameter phoneNumber).

        {
          "action" : {
            "text" : "Trouver MTarget",
            "postbackData" : "user_clicked_trouver_mtarget",
            "viewLocationAction" : {
              "latLong" : {
                "latitude" : 43.550808,
                "longitude" : 1.501273
              },
              "label" : "MTarget"
            }
          }
        },

The object action has a text which appears in the bubble, a postbackData which will be returned in the MO and a viewLocationAction which identifies the action as a localisation and awaits latLong (latitude and longitude) with the 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"
            }
          }
        },

The object action has a text which appears in the bubble, a postbackData which will be returned in the MO and a createCalendarEventAction which identifies the action as an event to add to the calendar which awaits the parameters startTime, endTime, title and description.

        {
          "action" : {
            "text" : "Visiter le site",
            "postbackData" : "user_clicked_visiter_le_site",
            "openUrlAction" : {
              "url" : "https://www.mtarget.fr/"
            }
          }
        },

The object action has a text which appears in the bubble, a postbackData which will be returned in the MO and a openUrlAction which identifies the action as a website to visit and awaits the parameter url.

        {
          "action" : {
            "text" : "Se renseigner en vidéo",
            "postbackData" : "user_clicked_se_renseigner_en_video",
            "openUrlAction" : {
              "url" : "https://youtu.be/_LXxFAo6sLY"
            }
          }
        }

The object action has a text which appears in the bubble, a postbackData which will be returned in the MO and a openUrlAction which identifies the action as a video to visit and awaits the parameter url.

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).