Apprendre à envoyer des SMS avec l'API SMS d'Orange

L'API SMS d'Orange disponible dans certains pays en zone d'Afrique et Moyen-Orient permet l'envoi et la réception de SMS vers les mobiles du monde entier, quel que soit l'opérateur. Il vous permet de toucher plus rapidement votre cible comparé à l'email.

Ce tutoriel porte sur le cas Nodejs, mais vous trouverez sur ce lien, l'API pour le langage PHP

L'API peut être utile pour envoyer un accusé de réception d'une livraison, diffuser des informations à une liste de clients, souhaiter la bonne année à une liste de numéros, créer un groupe de discussion par SMS, organiser un sondage.

Pour consommer l'API SMS d'Orange, vous avez besoin d'identifiants qui seront créés pour intégrer l'API à votre application et envoyer des SMS. Pour pouvoir appeler l'API SMS, vous devez déterminer le client ID et le client secret de l'application appelante.

Pour déterminer le client ID et le client secret de votre application, procédez comme suit :

1. Cliquez sur Sign in et connectez-vous à l'aide de l'adresse électronique que vous avez spécifiée lors de la souscription :

   

2. Cliquez sur My apps et sélectionnez le nom de votre application :

   

3. En cliquant sur le bouton show et on saisissant le mot de passe de votre compte, vous pouvez afficher les paramètres d'authentification unique à votre application :

Vous récupérez vos identifiants nécessaires pour coder votre script d'appel à l'API SMS :

• Application ID (identifie votre application) ;
• Client ID (authentifie votre application) ;
• Secret ID (sécurise votre application) ;
• Authorization header (autorise l'application à accéder aux méthodes choisies).

Maintenant que vous possédez vos clés d'authentification, vous pouvez demander à Orange un token permettant de faire les requêtes à l'API SMS. Pour ce faire, vous devez faire un appel à une requête de demande de token, en utilisant la méthode POST sur endpoint /oauth/v2/token, le développeur crée la fonction de génération de token comme le montre l'exemple ci-dessous en NodeJs :

function getToken (CLIENT_ID, CLIENT_SECRET, res ) {
    credentials="Basic djNaMzlSVzhpWHlVcHQxZmJ6RzVvdFhHSFkweW5WdFk6R3paT2lNeHhzOGlkVlN5XXXX";
    var postData = "";
    postData += "grant_type=client_credentials";
    try {
        var options = {
            host: 'api.orange.com',
            path: '/oauth/v2/token'
        };
        options['method'] = 'POST';
        options['headers'] = {
            'Authorization': credentials,
            'Content-Type': 'application/x-www-form-urlencoded',
            'Content-Length': Buffer.byteLength(postData)
        };
        var req = https.request (options, function(response) {
            response.setEncoding('utf8');
            var responseData = '';
            response.on ('data', function(data) { responseData += data; });
            response.on ('end', function() { var result = JSON.parse (responseData); });
       })
       .on('error', function(e) { });
       req.write(postData);
       req.end();
    }
}

Dans cette fonction qui prend pour paramètres (client id et secret id) déclarés au début du code, le développeur appelle la requête de génération de token mis dans l'objet options en utilisant la méthode POST. Si la méthode POST retourne un succès, le corps de la réponse au format JSON est stocké dans la variable result. Cette dernière contient alors toute la réponse de la requête c'est-à-dire token type, access_token et expires_in. Ensuite pour avoir votre token, vous devez faire result.access_token qui sera utilisé dans les paramètres de la fonction d'envoi de SMS.

L'autorisation header pourrait être calculé avec le mot clé Basic, suivi par un espace et de l'encodage en base64 de la concaténation de votre client_id, ":" et de votre client_secret :

Authorization header = Basic "+new Buffer(CLIENT_ID+":"+CLIENT_SECRET).toString('base64')

Si la méthode POST retourne un succès, le corps de la réponse au format JSON doit être similaire à :

Maintenant que vous avez un token qui vous permet d'accéder à tous les API SMS. Celui-ci est stocké dans la valeur associée à access_token. Ce token sera valide pendant le nombre de secondes retournées dans la clé "expires_in" (à noter que 7776000 secondes équivaut à 90 jours).

L'environnement est prêt, les identifiants sont créés, vous êtes prêt pour coder votre premier appel à l'API SMS.

Afin d'envoyer des SMS depuis notre API, vous devez tout d'abord acheter un bundle de SMS depuis le bouton « Configure » depuis l'application dans le menu « Dashboard ».

Depuis votre application, vous n'avez besoin que de quelques lignes de codes pour envoyer des SMS à vos clients. Pour cela, vous allez utiliser le token généré précédemment dans l'en-tête « Autorization » et accéder au endpoint suivant /smsmessaging/v1/outbound/{senderAddress}/requests.

L'appel aux API depuis un programme se fait aussi simplement. À titre d'exemple, nous présentons ci-dessous l'envoi de SMS en Node JS.

Node js :

function send (receiver, messagee, res) {
 var receveirr = "tel:"+receiver;
    var headers = {
        'Authorization': credentialss,
        'Content-Type': 'application/json'};
var body = {
        outboundSMSMessageRequest: {
    address : receveirr, 
        senderAddress : sender,
    outboundSMSTextMessage: {
        message : messagee    
}}};   
 var options = {
        uri: 'https://api.orange.com/smsmessaging/v1/outbound/tel:+22578432080/requests',
        method: 'POST',
        headers: headers,
        body: JSON.stringify(body)};
    request(options, function (error, response, body) {
if (!error && response.statusCode == 201) {
        res.render('sent');
        }        
        else {
res.render('contractsB');
        }
    })}

Pour pouvoir appeler la requête d'envoi de sms vous avez besoin de déterminer le token (credentialss) comme indiqué précédemment ensuite vous mettez dans le body (receiver, sender et le message) que vous voulez envoyer.

Si tout se passe bien et que vous n'avez pas d'erreurs, le SMS sera envoyé avec succès et vous recevrez une notification d'accusé de réception automatiquement après l'envoi ; sinon vous obtiendrez un message d'erreur avec une description de l'erreur dans le JSON.

Maintenant que vous êtes en possession de vos paramètres d'authentification (client id, secret id, authorization header et Token), vous pouvez passer des requêtes d'administration vers l'API SMS comme suit :

Par exemple vous pouvez avoir besoin de vérifier et d'afficher le nombre de SMS que vous pouvez toujours envoyer à vos clients. Pour cet usage, il suffit d'utiliser le token généré précédemment dans l'en-tête d'autorisation et d'accéder à la requête http://api.orange.com/sms/admin/v1/contracts comme ci-dessous en

Node js :

function GetContracts (res, accessToken) {
    credentialss =  "Bearer "+accessToken;
    try{
        var options = {
            host: 'api.orange.com',
            path: '/sms/admin/v1/contracts'
        };
        options['headers'] = { 'Authorization': credentialss, };            
        var req = https.get (options, function(response) {
            response.setEncoding('utf8');
            var responseData = '';
            response.on ('data', function(data) { responseData += data;  });
            response.on ('end', function() {
                var userr = JSON.parse (responseData);
                user = JSON.stringify(userr);
                res.render('contracts', {user: user});
            });
        })
        .on('error', function(e) { createErrorPage (res, e.message); });
    } 
    catch (e) {
        console.log ("exception during getUserData: "+e);
        createErrorPage (res, e);
    }
}

Exemple de réponse à la requête :

Pour plus de détails, veuillez accéder au getting started et sdk depuis ces liens :

• http://documentation.paddock.kermit.orange-labs.fr/smsapi-getting_started-v1.1.pdf ;
• https://developer.orange.com/tools/code-samples-and-sdk.

L'API SMS d'Orange est idéale pour toutes vos applications. Elle vous permet d'intégrer rapidement l'envoi de SMS à partir de nos serveurs. L'intégration de l'API SMS est simple, rapide et facile. Pour essayer dès aujourd'hui l'API SMS d'Orange, il suffit de vous souscrire sur le site developer orange avec votre adresse email ensuite vous intégrez l'API SMS à votre application. Les SMS sont largement utilisés pour diffuser des informations pratiques, suivre l'état d'une commande, être alerté d'un évènement inhabituel ou encore rappeler des rendez-vous. L'équipe de support reste à votre disposition pour toute information sur l'API SMS.

Nous remercions Meriem El Azaoui, pour la rédaction de ce tutoriel et Malick Seck pour la relecture orthographique. Nos remerciements vont également à Ismael Toé, pour la création de la bibliothèque pour PHP.