Utilisation de l’API Fastermessage

L’API Fastermessage est une API RESTFUL 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 d’envoi et à vos données de facturation soit directement sur la plateforme ou via l’API.

Création d’une clé d’API

Pour commencer, vous devez d’abord avoir un compte sur Fastermessage. Si vous ne l’avez pas déjà fait, rendez-vous ici pour créer votre compte. Dès que vous valider votre compte, vous pouvez vous connecter sur Fastermessage avec vos identifiants. Votre clé est créée en même temps que votre compte. Allez dans le menu « Développeur », vous y trouverez la clé associée à votre compte Fastermessage. C’est cette clé que vous utiliserez pour envoyer des SMS plus tard via l’API.

Envoyer un SMS

Pour envoyer un SMS par l’intermédiare de l’API, il vous faut lancer une requête HTTP vers l’adresse « https://api.fastermessage.com/v1/sms/send », en spécifiant certains paramètres (texte à envoyer, numéro de téléphone, destinataire, expéditeur, etc.). L’API va vous retourner une réponse sur l’état de la requête soumise : une confirmation de réponse si tout s’est bien passé ou une erreur si elle n’a pas les options de configuration disponibles.


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

  • X-API-KEY : ce paramètre est 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. 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 en une fois est 3 donc 459 caractères ;

  • 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 SMS précédé de l’indicatif de son pays. Exemple : 22990909090

  • datetime : pour envoyer votre message à une date et une 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.

Note

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 d’une requête pour l’envoi d’un SMS avec une fonction PHP :

  • 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;
}
?>

Note

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.

Réponse après envoi

Après l’envoi d’un SMS via l’API Fastermessage, vous obtiendrez une réponse du serveur en retour au format JSON comme ci-après.

{
  "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 contenu du SMS envoyé ;

  • from : c’est l’expéditeur du SMS envoyé ;

  • to : c’est le destinataire du SMS envoyé ;

  • code : c’est le code du status du SMS. Il peut prendre les valeurs 0 (rejeté), 1 (en attente), 2 (programé), 3 (délivré) ;

  • description : c’est le message descritptif du code status du SMS ;

  • smsCount : c’est le nombre de page que du SMS envoyé. Rappelons qu’une page SMS est de 160 caractères théoriques et de 153 caractères pratiques. 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 d’une page d’un SMS envoyé ;

  • messagePrice : c’est le coût total du SMS envoyé ;

  • messageId : c’est l’identifiant du message envoyé ;

Accusé de réception

Après chaque SMS envoyé, Fastermessage élabore un rapport détaillé sur l’accusé de réception de l’envoi. Vous pouvez consulter le rapport d’envoi sur la plateforme ou le récupérer automatiquement dans votre application en spécifiant l’argument dlr_url lors de la soumission de la requête d’envoi d’un SMS. Le rapport est soumis à votre application par la méthode POST.


Les variables présents dans le rapport d’accusé de réception d’un SMS 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"
}

Note

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 d’un SMS, 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 SMS.

Vérifier son solde

Pour vérifier le solde de votre compte Fastermessage via l’API, vous devez soumettre une requête HTTP à l’adresse suivante : « 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 renvoyée par l’API est au format JSON comme suit :

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

Toute l’équipe de Fastermessage s’efforce à vous offir la meilleure expérience d’envoi de SMS au meilleur prix partout dans le monde. Pour toute assistance technique, vous pouvez contacter notre équipe par mail à « assistance@fastermessage.com ». Elle est disponible 24h/24 et 7j/7 pour vous assister pour l’intégration de l’API et pour répondre à toutes vos questions. Enfin, pour toutes vos préoccupations concernant la facturation, vous pouvez contacter l’équipe de facturation par mail à « sale@fastermessage.com ».