API RCS

Inscription

RCS (Rich Communication Services) est un protocole permettant l'envoi de messages multimédias vers vos clients utilisateurs de l'OS Android au travers d'un agent dédié à votre marque ou votre enseigne.

L'usage de ces API est conditionné par deux éléments :

L'ouverture d'un agent auprès des opérateurs français métropolitains, pour cela il vous faut remplir le formulaire accessible ici. Une fois rempli le formulaire devra être retourné accompagné les éléments graphiques attendus à support@mtarget.fr et csm@mtarget.fr avec comme sujet de mail "Ouverture d'un AGENT RCS".

L’ouverture d’un compte pour tester notre service. La création d'un compte est gratuite et sans engagement. Pour ouvrir un compte envoyez un mail à support@mtarget.fr et csm@mtarget.fr avec comme sujet de mail "Création d'un compte API RCS" et en précisant vos coordonnées :

  • email du compte
  • nom
  • prénom
  • nom de la société
  • Siret
  • numéro de téléphone mobile

En retour, nous vous fournissons les identifiants nécessaires à l'utilisation de l'API.

Le compte d'envoi que nous vous ouvrons peut supporter plusieurs offres et tarifs différents en fonction des destinations et des opérateurs, n’hésitez pas à nous préciser les destinations que vous souhaitez tester.

Requête simplifiée

Cette requête est basée sur notre API d'envoi de SMS avec l'ajout d'un paramètre agentMessage dont le contenu va être décrit dans la partie Composants.

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné

 agentmessage{"contentMessage": [{ "example" : "value"}]}

Ce paramètre doit toujours contenir un objet contentMessage.

Composants

Le RCS permet d'envoyer des messages complexes qui ne sont plus du simple texte. Pour cela, il faudra respecter la syntaxe précise d'un objet json qui sera décrite ci-dessous.

Texte simple

Cette méthode permet d'envoyer un message ne contenant que du texte. On obtient un rendu "classique" de SMS avec dans la petite bulle l'image choisie par vous à la création de l'agent :

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné

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

Dans le JSON, le paramètre text est renseigné et peut contenir des caractères spéciaux et des émojis jusqu'à 3072 caractères

Fichier simple

Cela vous retournera un résultat comme ci-dessous :

Les ratios d'images recommandés sont :

  • Carte verticale : 2:1, 16:9, 7:3 (en pixels : 1440x720, 1440x810, 1440x617)
  • Carte horizontale : 3:4 (en pixels : 768*1024)
POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné

 agentmessage{"contentMessage": {"contentInfo": {"fileUrl": "https://yourpublicimage.jpg"}}}

Dans le JSON, l'objet contentInfo est ajouté contenant le paramètre fileUrl qui doit pointer vers un fichier publiquement accessible.

Rich card seule

Cela vous retournera un résultat comme ci-dessous :

ou encore

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné

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

Ce JSON est expliqué dans la partie suivante.

Rich card seule json

Ici, le contentMessage contient l'élément richCard qui lui même contient l'objet standaloneCard. Cet objet contient des propriétés relatives à l'objet global comme son orientation. Il contient aussi la carte en elle-même cardContent qui décrit son titre, sa description et son image (dans l'objet media).



Card seule verticale
{ "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 défini où le texte se trouvera par rapport à l'image. Ici, "VERTICAL" signifie que le texte sera en dessous de l'image. Lorsque ce paramètre est utilisé, il faut aussi renseigner un paramètre height à l'image qui doit être SHORT/MEDIUM/TALL.
Card seule horizontale
{ "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 défini où le texte se trouvera par rapport à l'image. Ici, "HORIZONTAL" signifie que le texte sera à gauche ou à droite de l'image. Lorsque ce paramètre est utilisé, il faut aussi renseigner un paramètre thumbnailImageAlignment à l'objet standaloneCard qui doit être LEFT/RIGHT.


Carrousel de rich cards

Cela vous retournera un résultat comme ci-dessous :

POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné

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

Ce JSON est expliqué dans la partie suivante.

Carrousel de rich card json

Ici, le contentMessage contient l'élément richCard qui lui même contient l'objet carouselCard. Cet objet contient la propriété de la largeur des cartes (cardWidth) qui ne peut prendre comme valeur que SMALL ou MEDIUM. Il contient aussi un tableau cardContents (à noter le S) qui contient donc des éléments cardContent qui décrivent les titres, descriptions et images présentes dans le carrousel.



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

Cela vous retournera un résultat comme ci-dessous :


POST https://api-public-2.mtarget.fr/messages HEADERS
Content-Typeapplication/x-www-form-urlencoded;charset=utf-8


 BODY
usernameUSERNAME

Votre username fourni à l'inscription

 passwordPASSWORD

Votre password fourni à l'inscription

 msisdnMSISDN

Numéro du destinataire avec indicatif (+33...) ou au format international (0033...). Vous pouvez ajouter jusqu'à 500 msisdn séparés d'une virgule : +336xxxx1,+336xxxx2,+336xxxx3

 msgWhatever

Ce paramètre est obligatoire mais inutilisé si le paramètre agentMessage est renseigné.

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

Ce JSON est expliqué dans la partie suivante.

Suggestions json

Ici, le contentMessage retrouve une valeur text et des bulles sont affichées en dessous du messages. Ces bulles sont différentes actions définies ci-dessous.



{
  "contentMessage" : {
    "text" : "Hey, voici quelques suggestions ⬇",
    "suggestions" : [
  
        {
          "reply" : {
            "text" : "Coucou",
            "postbackData" : "user_clicked_coucou"
          }
        },
Un simple message qui sera envoyé par l'utilisateur comme s'il l'avait écrit. Veuillez noter que ce n'est pas un objet action mais une reply. 
        {
          "action" : {
            "text" : "Appeler !",
            "postbackData" : "user_clicked_appeler",
            "dialAction" : {
              "phoneNumber" : "+33561251255"
            }
          }
        },
L'objet action contient un text qui apparaît sur la bulle, un postbackData qui remontera dans le MO et surtout le dialAction qui identifie l'action comme étant un appel (en lui renseignant son paramètre phoneNumber). 
        {
          "action" : {
            "text" : "Trouver MTarget",
            "postbackData" : "user_clicked_trouver_mtarget",
            "viewLocationAction" : {
              "latLong" : {
                "latitude" : 43.550808,
                "longitude" : 1.501273
              },
              "label" : "MTarget"
            }
          }
        },
L'objet action contient un text qui apparaît sur la bulle, un postbackData qui remontera dans le MO et surtout le viewLocationAction qui identifie l'action comme étant une localisation qui attend un objet latLong qui doit lui renseigner sa latitude et longitude avec comme 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"
            }
          }
        },
L'objet action contient un text qui apparaît sur la bulle, un postbackData qui remontera dans le MO et surtout le createCalendarEventAction qui identifie l'action comme étant un évènement à ajouter au calendrier qui attend les paramètres startTime, endTime, title et description. 
        {
          "action" : {
            "text" : "Visiter le site",
            "postbackData" : "user_clicked_visiter_le_site",
            "openUrlAction" : {
              "url" : "https://www.mtarget.fr/"
            }
          }
        },
L'objet action contient un text qui apparaît sur la bulle, un postbackData qui remontera dans le MO et surtout le openUrlAction qui identifie l'action comme étant un site à visiter qui attend le paramètre url. 
        {
          "action" : {
            "text" : "Se renseigner en vidéo",
            "postbackData" : "user_clicked_se_renseigner_en_video",
            "openUrlAction" : {
              "url" : "https://youtu.be/_LXxFAo6sLY"
            }
          }
        }
L'objet action contient un text qui apparaît sur la bulle, un postbackData qui remontera dans le MO et surtout le openUrlAction qui identifie l'action comme étant une vidéo à visiter qui attend le paramètre url. 
    
    ]
  }
}


Suggestions et carrousel

Vous pouvez ajouter une suggestion aux cards dans les carrousels de la façon suivante :



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

A la fin, vous obtenez un résultat semblable à :


Charset dans le header

Attention à bien garder dans votre header Content-Type le charset utilisé (dans nos exemples, utf-8) par votre outil d'envoi. Sans ce header, notre API interprète mal le contenu du agentmessage (on traite de l'iso 8859-1 par défaut pour des raisons legacy).

Notifications - Code RSN

A la suite de l'envoi d'un RCS, vous recevez sur votre URL de notification un certain nombre d'informations détaillées ici.


Voici la liste des codes RSN spécifiques au RCS et leurs explications :


 Code RSN  | Explication
----------------------------------------------------------
    400    | L'URL du fichier fournis n'est pas accessible
    403    | Opérateur non compatible RCS
    404    | Utilisateur non compatible RCS
    503    | Incident Google
    999    | Incident divers