Fastermessage - Guide d'utilisation de l'API

Prise en main

Bienvenu sur Fastermessage !

Fastermessage est une solution d'envoi de message court (sms) en temps réel et différé qu'il faut pour vos activités. C'est une solution simple, rapide et légère. L'api de Fastermessage est un RESTFUL API qui vous permet d'envoyer des sms via votre application (web, mobile, etc.). Après chaque envoi, vous avez la possibilité d'accéder à l'historique des rapports d'envoi et à vos données de facturation soit directement sur la plateforme ou via l'API.

Création de compte

Pour commencer, vous devez d'abord créer un compte sur Fastermessage si vous ne l'avez pas déjà fait. Rendez-vous ici pour créer votre compte. Une fois le compte créé, un email vous est automatiquement envoyé contenant le lien de validation de votre compte. Dès que vous valider votre compte, vous pouvez vous connecter sur Fastermessage avec vos identifiants créés. Vous disposez d'un solde initial à la création pour faire vos premiers tests d'envois de sms soit sur la plateforme ou via l'API.

Création d'une clé d'API

Avant de commencer à faire vos envois via l'api, vous devez d'abord générer votre clé d'envoi. Pour ce faire, connectez-vous sur Fastermessage avec les identifiants de votre compte. Aller dans la rubrique développeur. Vous y trouverez la clé de l'api associée à votre compte Fastermessage. C'est cette clé que vous utiliserez pour l'envoi des sms plus tard.


Intégration de l'API

Envoi de message

Pour envoyer des SMS via l’API, il vous faut lancer une requête http vers l'adresse de l'api https://api.fastermessage.com/v1/sms/send, en utilisant certains paramètres (texte à envoyer, numéro de téléphone, destinataire, expéditeur, etc.). L'api retourne une réponse sur l'état de la requête soumise, une confirmation de réponse que tout s'est bien passé, ou une réponse d'erreur si elle n'a pas Les options de configuration disponibles.

Les paramètres prisent en compte pour l’envoi de message via l'API sont :

  • X-API-KEY : ce paramètre représente la clé d'authentification de l'api associée à votre compte. Il vous permet de vous identifier à travers la requête http ;
  • text : c'est le message à envoyer. Une page sms est de 160 caractères théoriques et de 153 caractères pratiques. Car certains caractères sont comptés en double comme le caractère de retour chariot. Le nombre limité de page sms que vous pouvez envoyer est 3 donc 459 caractères à la fois ;
  • from : c’est l’expéditeur du message. C’est un paramètre de type alphanumérique qui peut être un nom, un numéro de téléphone, etc. Les caractères spéciaux sont interdits. Il est d'au plus 11 caractères ;
  • to : c’est le destinataire du message. Il s’agit du numéro de téléphone de celui qui reçoit le message précédé de l’indicatif de son pays. Exemple : 22990909090
  • dateTime : pour envoyer votre message à une date et heure donnée, vous devez spécifier ce paramètre au format suivant : YYYY-MM-DD HH:II:SS. Notez que le fuseau horaire pris en charge par l'api est UTC+1 ;
  • messageId : c’est l’identifiant unique du message. S'il n'est pas spécifié, un identifiant lui sera attribué automatiquement par l'api ;
  • dlr_url : c’est l'adresse http à laquelle l'accusé de réception du message vous sera envoyé automatiquement. Voir la rubrique accusé de réception pour plus de détail ;
  • Remarque : les variables en rouge sont obligatoires. Les autres sont optionnelles.

Vous pouvez soumettre la requête avec la méthode GET ou POST. Voici ci-dessous un exemple de fonction PHP de requête pour l'envoi de sms :

  • Méthode POST
      <?php
      	function fastermessage($from, $to, $text, $messageId, $dateTime)
        {
            $url            = 'https://api.fastermessage.com/v1/sms/send/';
            $apiKey         = '1234567890';
            $smsData        = array(
                'from'      => $from, 
                'to'        => $to, 
                'text'      => $text,
                'messageId' => $messageId,
                'dateTime'  => $dateTime,
                'dlr_url'   => 'https://mydomain.com/myclass/mymethod/',
            );
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_TIMEOUT, 30);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
            curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
            curl_setopt($ch, CURLOPT_HTTPHEADER, array("X-API-KEY: " . $apiKey));
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS, $smsData);
            $result = curl_exec($ch);
            curl_close($ch);
            return $result;
        } 
      ?>
  • Méthode GET
      <?php
        function fastermessage($from, $to, $text, $messageId, $dateTime)
        {
            $apiKey         = '1234567890';
            $sendsmsurl_prefix = "https://api.fastermessage.com/v1/sms/send/";
            $curl = curl_init();
            $sendsmsurl_params = array(
                                'from'      => $from, 
                                'to'        => $to, 
                                'text'      => $text,
                                'messageId' => $messageId,
                                'dateTime'  => $dateTime,
                                'dlr_url'   => 'https://mydomain.com/myclass/mymethod/',
                        );
                        
            $sendsmsurl = $sendsmsurl_prefix."?".http_build_query($sendsmsurl_params);

            curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);
            curl_setopt($curl, CURLOPT_HTTPHEADER, array("X-API-KEY: " . $apiKey));
            curl_setopt($curl, CURLOPT_URL, $sendsmsurl);

            $result = curl_exec($curl);
            curl_close($curl);
            return $result;
        } 
      ?>

Remarque : Ces deux fonctions ne sont données qu'en guise d'exemple. Quelques soit votre langage de programmation, vous pouvez simplement envoyer un sms en soumettant une requête http avec les paramètres directement dans l'url comme dans l'exemple ci-dessous :

https://api.fastermessage.com/v1/sms/send?X-API-KEY=1234567890&from=kora&to=22990909090&text=Bonjour

Réponse après envoi

        {
          "status" : true,
          "from" : "Fastermessage",
          "to" : "22966566656",
          "text" : "Hello-World-!",
          "code" : 1,
          "description" : "Accepted for delivery",
          "smsCount" : 1,
          "devise" : "XOF",
          "unitPrice" : "12",
          "messagePrice" : 12,
          "messageId" : "1550226919288536"
        }
      

Passons en revue les informations renvoyées par le serveur à la suite de la requête d'envoi :

  • status : c'est l'état de soumission de la requête. Il est TRUE si tout s'est bien passé ou FALSE s'il y a un problème
  • text : c'est le message envoyé ;
  • from : c’est l’expéditeur du message envoyé ;
  • to : c’est le destinataire du message envoyé ;
  • code : c'est le code du status du message. Il peut prendre les valeurs 0 (rejeté), 1 (en attente), 2 (programé), 3 (délivré).
  • description : c'est le message descritptif du code de message ;
  • smsCount : c’est le nombre de page sms que fait le message envoyé. Rappelons qu'une page sms est de 160 caractères théoriques et de 153 caractères pratiques. Car certains caractères sont comptés en double comme le caractère de retour chariot ;
  • devise : c’est la devise de facturation de votre compte Fastermessage ;
  • unitPrice : c'est le prix unitaire du message envoyé ;
  • messagePrice : c’est le coût total du message envoyé ;
  • messageId : c’est l'identifiant du message envoyé ;

Accusé de réception

Pour chaque message envoyé, Fastermessage tient un rapport détaillé sur l'accusé de réception de l'envoi. Vous avez la possibilité de consulter le rapport d'envoi sur la plateforme ou le récupérer automatiquement dans votre application en spécifiant la variable dlr_url lors de la soumission de la requête d'envoi du sms ou le consulter en différé quand vous voulez en soumettant la requête de récupération du rapport d'envoi.

Lorsque vous spécifiez la variable dlr_url, votre lien est appelé automatiquement dès que le rapport d'envoi est disponible. Les variables sont soumis à votre lien par la méthode POST. Les variables concernant le rapport d'accusé de réception du message sont les suivants :

        {
          "messageId": "1234567890",
          "from": "FASTERSMS",
          "to": "22990909090",
          "text": "Ceci est le message envoyé",
          "smsCount": "1",
          "devise": "XOF",
          "unitPrice": "12",
          "messagePrice": 12,
          "messageStatusCode": "3",
          "messageStatus": "Delivered",
          "description": "Message delivered to handset",
          "timeZone": "UTC+1",
          "creationDate": "2019-03-12 15:43:14",
          "sendingDate": "2019-03-12 15:40:45",
          "deliveryDate": "2019-03-12 15:43:15"
        }
      

Si vous décidez de récupérer ce même rapport d'accusé de réception en différé, c'est-à-dire bien après l'envoi, vous envoyez votre requête vers le lien suivant par la méthode GET ou POST : http://api.fastermessage.com/v1/sms/dlr/?messageId=1234567890 avec messageId, l'dentifiant unique du message.

Vérification de solde

Pour vérifier le solde de votre compte Fastermessage via l'api, vous devez soumettre une requête https vers le lien suivant : http://api.fastermessage.com/v1/sms/balance en spéciant la clé d'authenification de votre compte. Voici ci-dessous un exemple de code PHP.

      <?php
        function fastermessage()
        {
            $url            = 'https://api.fastermessage.com/v1/sms/balance/';
            $apiKey         = '1234567890';
            
            $ch = curl_init($url);
            curl_setopt($ch, CURLOPT_TIMEOUT, 30);
            curl_setopt($ch, CURLOPT_RETURNTRANSFER,1);
            curl_setopt($ch, CURLOPT_HTTPAUTH, CURLAUTH_ANY);
            curl_setopt($ch, CURLOPT_HTTPHEADER, array("X-API-KEY: " . $apiKey));
            curl_setopt($ch, CURLOPT_POST, 1);
            curl_setopt($ch, CURLOPT_POSTFIELDS, '');
            $result = curl_exec($ch);
            curl_close($ch);
            return $result;
        } 
      ?>

La réponse que renvoie l'api est la suivante :

        {
          "balance": "430",
          "unitPrice": "0.01",
          "devise": "EUR"
        }
      
  • balance : c'est le solde disponible de votre compte Fastermessage ;
  • unitPrice : c'est le prix unitaire auquel le sms vous est facturé ;
  • devise : c’est la devise de votre compte Fastermessage

Support technique

Pour toute assistance technique, notre équipe est à votre disposition 24h/24, 7j/7 pour vous assister lors de l'intégration de l'api et pour répondre à toutes vos préoccupations. Veuillez nous contacter par mail à assistance@fastermessage.com. Pour toutes vos préoccupations concernant la facturation, veuillez joindre l'équipe de facturation par mail à sale@fastermessage.com. Toute l'équipe de Fastermessage s'attèle à la tâche pour vous offir la meilleure expérience d'envoi de sms au meilleur prix partout dans le monde.

Dernière mise à jour : 19-03-2019