.wpb_animate_when_almost_visible { opacity: 1; }
SMS Africa and Middle East
Engage with your users via SMS in the Orange Middle East & Africa footprint. Purchase SMS bundles with your Orange SIM card and get started in minutes.
1.1

.


** French (FR) version **


Avec les API d'Orange et quelques lignes de code, vous pouvez très facilement envoyer des SMS, recevoir les accusés de réception, recevoir des SMS sur votre plateforme (SMS MO) et gérer votre compte en tant qu'administrateur.

Avant d'envoyer des SMS, vous devez obtenir des identifiants pour votre application/service depuis ce portail, indiquer les pays que vous souhaitez cibler et acheter un ou plusieurs bundles, c'est à dire des crédits d'envoi.

Afin de vous faciliter la découverte et l'intégration des API SMS pour votre service, Orange vous propose l'achat d'un Starter bundle ou pack de démarrage à très bas prix, directement depuis votre abonnement mobile. Note : ce pack ne peut être acheté qu'une seule fois par compte Orange Developer et numéro de téléphone mobile de développeur.

Notez que vous pouvez contacter à tout moment les équipes locales d'Orange depuis ce formulaire pour demander

  • "Sender name" - l'enregistrement d'une liste de sender name (sous réserve d'accéptation par l'équipe locale d'Orange; une preuve que vous êtes autorisé à utiliser chaun de sender names demandés vous sera demandée)
  • "Larger volumes" - acheter des volumes plus importants que ceux proposés
  • "SMS response" - nous transmettre une URL sur laquelle vous aller pouvoir recevoir des réponses par SMS
  • "Real time SMS DR" - nous transmettre une URL pour recevoir le notification d'envoi de SMS (delivery request)

Après avoir déclaré votre application, associé la ou les API SMS et payé votre pack / bundle, vous pouvez démarrer les étapes suivantes.

Authentification

Comme identifiants, vous avez simplement besoin de copier le {{{authorization_header}}} lié à votre application (disponible sur la page de votre application sur ce portail) pour demander un token via une simple requête POST au standard OAuth 2.0, comme indiqué ci dessous :

curl -X POST \
-H "Authorization: {{authorization_header}}" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Accept: application/json" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v3/token

note : le flag -d entraine implicitement le format : application/x-www-form-urlencoded

Vous recevez alors des données au format JSON, dont vous pouvez extraire votre {{access_token}}:

HTTP/1.1 200 OK
Content-Type: application/json
{
    "token_type": "Bearer",
    "access_token": "{{access_token}}",
    "expires_in": "3600"
}

Bonnes pratiques pour les tokens

L'access_token a une durée de vie de 3600 secondes, soit 1 heure. Donc vous n'avez pas besoin d'en redemander un nouveau avant chaque envoi de SMS. Il vous suffit de bien gérer les erreurs potentielles dans vos futurs appels et notamment détecter l'erreur de type out-of-date comme ci-dessous :

HTTP/1.1 401 Unauthorized
Content-Type: application/json
{
  "code": 42,
  "message": "Expired credentials",
  "description": "The requested service needs credentials, and the ones provided were out-of-date."
}

Dans ce cas, il vous suffit de redemander un nouveau token. Pour plus d'information sur les erreurs potentielles, merci de consulter le guide complet.

Envoi de SMS

Comme indiqué ci-dessus, il faut d'abord acheter un SMS bundle depuis la page de configuration de votre application, sur ce portail.

Pour envoyer un SMS à {{recipient_phone_number}}, vous devez simplement utiliser votre {{access_token}}, indiquer le {{country_sender_number}} comme senderAddress dans le corps de la requête et au niveau de l'url avec votre code pays mais sans préfixe + ou 00.

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
        "outboundSMSTextMessage":{ \
            "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

Le {{country_sender_number}} est mentionné deux fois : dans le corps (body) et dans l'url (endpoint) où tel:+ est encodé ainsi : tel%3A%2B (url-encoded).

Liste de country_sender_number par pays, avec un rappel du code standard ISO-3166 à trois lettres :

CountryCodecountry_sender_number
BotswanaBWAtel:+2670000
Burkina FasoBFAtel:+2260000
CameroonCMRtel:+2370000
Côte d'Ivoire / Ivory CoastCIVtel:+2250000
Guinea ConakryGINtel:+2240000
Guinea BissauGNBtel:+2450000
DR CongoCODtel:+2430000
JordanJORtel:+9620000
LiberiaLBRtel:+2310000
MaliMLItel:+2230000
MadagascarMDGtel:+2610000
SenegalSENtel:+2210000
TunisiaTUNtel:+2160000

Veuillez noter qu'un sender name par defaut sera automatiquement fixé par notre plateforme. Ce nom est lié à votre compte Orange Developer. Si vous souhaitez utiliser des sender names specifiques, vous devez contacter l'équipe locale d'Orange, comme expliqué en introduction de cette page. Par exemple si vous avez demander l'ajout du sender name "MonService" et que cela été validé par l'équipe locale Orange, pour envoyer des SMS étiquetés "MonService", vous devriez faire un appel comme suit

curl -X POST -H "Authorization: Bearer {{access_token}}" \
-H "Content-Type: application/json" \
-d '{"outboundSMSMessageRequest":{ \
        "address": "tel:+{{recipient_phone_number}}", \
        "senderAddress":"tel:+{{country_sender_number}}", \
                "senderName": "MonService", \
        "outboundSMSTextMessage":{ \
            "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{country_sender_number}}/requests"

Attention, si le sender name utilisé n'est pas configuré sur notre plateforme, vous allez recevoir une erreur.

Cette requête retourne des Headers et des données au format JSON contenant des informations sur le statut d'envoi de SMS, ou sinon la requête retourne alors une erreur HTTP avec le détail dans le JSON.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.orange.com/smsmessaging/v1/outbound/tel:+{{recipient_phone_number}}/requests/{{resource_id}}
Content-Length: 12345
Date: Thu, 01 Avr 2015 02:38:38 GMT

{
    "outboundSMSMessageRequest":{
        "senderAddress":"tel:+{{recipient_phone_number}}",
        "senderName": "test",
        "outboundSMSTextMessage":{
            "message":"Hello!"
        },
        "resourceURL":"https://api.orange.com/smsmessaging/v1/outbound/tel:+{{recipient_phone_number}}/requests/{{resource_id}}"
    }
}

Note : si le sender name utilisé n'est pas dans la liste enregistrée sur notre plateforme, vous obtiendrez une erreur : 400 requestError.

Vous obtenez en retour un {{resource_id}} comme unique identifiant (ID) que vous devez enregistrer si vous souhaitez par la suite le corréler avec d'autres informations, dont l'accusé de réception Delivery Receipt (DR). {{resource_id}} est une chaîne de caractères avec le format typique suivant : xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Note : Vous ne pouvez pas envoyer plus de 5 SMS par seconde.

A propos des accusés de réception

Chaque SMS envoyé va provoquer un accusé de réception SMS DR (Delivery Receipt) dans les 24 heures qui suivent. Pour le recevoir, vous devez créer un end-point sur votre propre backend / serveur.

Votre end-point ou URL de backend doit :

  • être sécurisée (par un certificat non auto-signé) et sous protocole https
  • être accessible depuis l'Internet, sur le PORT 443
  • retourner HTTP 200 OK pour confirmer la réception du SMS DR
  • être 'connue' par notre plateforme avant de pouvoir être utilisé; pour ce faire, connectez vous à votre compte Orange Developer et remplir ce formulaire pour transmettre l'URL de votre backend à nos équipes. Une fois votre backend configuré sur la plateforme Orange, notre équipe technique va vous transmettre une IP publique à white-lister de votre côté.

Note importante à propos du SMS DR Status

L'information SMS DR status n'est pas fiable à 100% sauf lorsque vous recevez un DeliveredToTerminal. En cas de status DeliveryImpossible, votre SMS peut encore être délivré (par ex. si un téléphone reste déconnecté du réseau ou simplement non alimenté pendant plus de 24 heures ; mais votre SMS a aussi pu être envoyé à un numéro fixe ou désactivé par ex. Orange ne rembourse pas les SMS non délivrés. Si vous recevez un retour, quelque soit le statut, cela veut dire que notre API fonctionne. Le fait que le SMS n'est peut-être pas reçu, ne peux pas être considéré comme un dysfonctionnement de l'API SMS d'Orange.

Exemple d'un SMS DR Request depuis Orange vers votre backend :

POST https://{{dev_host}}:443/orange/smsdr.php HTTP/1.1
Content-Type: application/json
{
    "deliveryInfoNotification":{
        "callbackData":"{{resource_id}}",
        "deliveryInfo":{
            "address":"tel:+{{recipient_phone_number}}",
            "deliveryStatus":"{{delivery_status}}"
        }
    }
}

Exemple de réponse :

HTTP/1.1 200 OK

Dans le corps JSON de la requête venant d'Orange, votre backend peut extraire 3 informations importantes :

  • {{resource_id}}: l'ID unique du SMS correctement envoyé
  • {{recipient_phone_number}}: le numéro de téléphone (MSISDN) de son destinataire
  • {{delivery_status}}: le status du SMS DR

{{delivery_status}} peut prendre différentes valeurs :

ValueDescription
DeliveredToNetworkBien acheminé au réseau
DeliveryUncertainStatus inconnu, par ex. car acheminé par un autre réseau
DeliveryImpossibleEchec de réception ; le message n'a pu arriver avant expiration
MessageWaitingLe message est toujours en file d'attente
DeliveredToTerminalBien reçu sur le terminal

A titre d'exemple, voici un code PHP permettant d'extraire le SMS DR sur votre backend :

<?php
    // ## RESPONSE HEADER ##
    $response_header="HTTP/1.1 200 OK";
    // ## RESPONSE BODY ##    
    $response_body="OK";
    // ### REQUEST BODY ###
    $request_body = file_get_contents('php://input');
    $json_request= json_decode( $request_body, TRUE ); //convert JSON into array
    if (isset($json_request['deliveryInfoNotification'])){
        $address=$json_request['deliveryInfoNotification']['deliveryInfo']['address'];
        $address = str_replace('tel:','',$address);    
        $deliveryStatus = $json_request['deliveryInfoNotification']['deliveryInfo']['deliveryStatus'];
        $callbackData=$json_request['deliveryInfoNotification']['callbackData'];
        // Then DO SOMETHING WITH THESE VALUES
        // ..
    }
?>

Votre solde d'envoi de SMS

Depuis votre application ou votre espace d'administration, vous pouvez consulter votre solde de SMS, c'est à dire combien de SMS vous pouvez encore envoyer, mais aussi la date d'expiration de votre pack restant. Pour cela, il suffit de réutiliser votre {{access_token}} avec le endpoint /sms/admin/v1/contracts, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/contracts"

Cette requête retourne les données de votre solde SMS et la date d'expiration, au format JSON :

{
    "partnerContracts":{
        "partnerId":"{{partner_id}}",
        "contracts":[
            {
                "service":"SMS_OCB",
                "contractDescription":"Your SMS balance (per country)",
                "serviceContracts":[
                    {
                        "country":"CIV",
                        "service":"SMS_OCB",
                        "contractId":"2117fc27-a121-46f2-933c-cd4ec6475d67",
                        "availableUnits":324,
                        "expires":"2015-05-01T14:38:14",
                        "scDescription":"Côte d'Ivoire - 324 SMS valid until before May 1, 2015 2:38 PM"
                    }
                ]
            }
        ]
    }
}

Note : vous pouvez ajouter un paramètre optionnel pour filtrer la réponse par pays, avec /sms/admin/v1/contracts?country={{country_code}}{{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici.

Note : {{partner_id}} est votre email de développeur déclaré.

Bilan d'usage des SMS

Depuis votre application ou votre espace d'administration, vous pouvez consulter le nombre de SMS envoyés par application et par pays. Pour cela, réutilisez votre {{access_token}} en appelant le end-point: /sms/admin/v1/statistics, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/statistics"

Cette requête retourne votre consommation de SMS par application (et par pays), au format JSON :

{
    "partnerStatistics":{
        "partnerId":"{{partner_id}}",
        "statistics":[
            {
                "service":"SMS_OCB",
                "serviceStatistics":[
                    {
                        "country":"CIV",
                        "countryStatistics":[
                            {
                                "applicationId":"45153daa87e...84e8e4ba",
                                "usage":153
                            },
                            {
                                "applicationId":"45153daa87e...4d735trf",
                                "usage":23
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Vous pouvez ajouter 2 paramètres optionnels pour filtrer par pays et application : /sms/admin/v1/statistics?country={{country_code}}&appid={{app_id}}

  • {{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici
  • {{app_id}} est l'ID de votre application que vous pouvez retrouver dans votre tableau de bord, sur ce portail.

Historique des achats

Vous pouvez retrouver l'historique de l'ensemble de vos achats de packs depuis votre compte. Pour cela, utilisez votre {{access_token}} en appelant le end-point : /sms/admin/v1/purchaseorders, comme ci-dessous :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"https://api.orange.com/sms/admin/v1/purchaseorders"

Cette requête retourne votre historique d'achat de packs SMS par application (et par pays), au format JSON. Exemple :

{
    "purchaseOrders":[
        {
            "purchaseOrderId":"24031977",
            "mode":"OCB",
            "bundleId":"bc8cda15-3409-495a-b5ab-87c7017816b1",
            "bundleDescription":"Bundle 2 - 500 SMS for 15 000 FCFA)",
            "partnerId":"53laht-s1-3r0m-naht-3m0s3wa",
            "inputs":[
                {
                    "type":"MSISDN",
                    "value":"+22557....11"
                },
                {
                    "type":"bundleId",
                    "value":"bc8cda15-3409-495a-b5ab-87c7017816b1"
                },
                {
                    "type":"confirmationCode",
                    "value":"22....10"
                },
                {
                    "type":"challengeMethod",
                    "value":"OTP-SMS-OCB"
                }
            ],
            "orderExecutioninformation":{
                "date":"2015-04-01T14:38:40",
                "amount":15000,
                "currency":"XOF",
                "service":"SMS_OCB",
                "country":"CIV",
                "contractId":"211...7-a121-46f2-933c-cd4...67"
            }
        }
    ]
}

Vous pouvez filtrer la réponse par pays en utilisant un paramètre optionnel : /sms/admin/v1/purchaseorders?country={{country_code}}{{country_code}} est le code standard international à 3 digits - par ex. CIV pour la Côte d'Ivoire. Tous les codes "ISO 3166 alpha 3" sont listés ici.

Vous pouvez aussi profiter de la collection Postman que nous avons préparée pour vous : Orange SMS MEA avec tous les appels essentiels et les variables d'environnement :

Run in Postman

Ce lien vous permet de télécharger et activer directement Postman en même temps que les collections. En cas de problème, vous pouvez installer séparément Postman, depuis ce lien.

La collection comprend les 5 requêtes API principales :

  • Authentication (POST)
  • Send SMS (POST)
  • View SMS balance (GET)
  • View SMS usage (GET)
  • View Purchase history (GET)

L'environnement Postman inclut les variables suivantes :

  • authentication_header: identification/code pour votre application, à copier depuis ce portail et à coller dans le champ current value de la variable, et ce, avant votre tout premier envoi de requête
  • access_token: extrait (parsed) depuis la réponse à la requête POST Authentication POST
  • dev_phone_number: votre numéro de téléphone mobile Orange
  • recipient: le numéro de mobile de votre destinataire
  • partner_id: extrait automatiquement
  • resource_id: extrait automatiquement

Note : l'extraction (parsing) des valeurs dans les réponses aux requêtes s'effectue automatiquement grâce au code Javascript inséré dans la collection Postman (cf "test" tab).

Note2 : Si vous utilisez une version de Windows antérieure à Windows-10 ou si vous rencontrez un problème dans le téléchargement ou l’ouverture de l’appli Postman, veuillez alors la télécharger depuis leur site (https://www.getpostman.com/), puis importer dans l’application la collection et l’environnement que nous avons regroupés dans un zip à télécharger ci-dessous : (clic droit + "enregistrer la cible du lien sous" / ou "save link as", si la popup de chargement ne s'affiche pas)