.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 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.

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}}" \
-d "grant_type=client_credentials" \
https://api.orange.com/oauth/v2/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": "7776000"
}

Bonnes pratiques pour les tokens

L'access_token a une durée de vie de 7776000 secondes, soit 90 jours. 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 votre {{dev_phone_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:+{{dev_phone_number}}", \
        "outboundSMSTextMessage":{ \
            "message": "Hello!" \
        } \
    } \
}' \
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{dev_phone_number}}/requests"

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

Exemples de sender addresses SMS par pays, avec un rappel du code standard ISO-3166 à trois lettres :

CountryCodeSender address
BotswanaBWAtel:+2670000
Burkina FasoBFAtel:+2260000
CameroonCMRtel:+2370000
Côte d'Ivoire / Ivory CoastCIVtel:+2250000
DR CongoCODtel:+2430000
EgyptEGYtel:+200000
JordanJORtel:+9620000
Guinea ConakryGINtel:+2240000
MaliMLItel:+2230000
NigerNERtel:+2270000
SenegalSENtel:+2210000
TunisiaTUNtel:+2160000

Veuillez noter que le sender name de votre SMS sera automatiquement fixé par notre plateforme. Ce nom est lié à votre compte Orange Developer.

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.

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.

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 signé) et sous protocole https
  • être accessible depuis l'Internet, sur le PORT 443
  • être whitelisté (par son IP) sur le serveur API-SMS avant de pouvoir être utilisé : pour ce faire, Merci de remplir le formulaire
  • retourner HTTP 200 OK pour confirmer la réception du SMS DR

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

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.

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
        // ..
    }
?>

Au cas où votre backend implémente une protection par adresse IP, veuillez autoriser dans votre "white-list" les adresses de nos propres backends Orange :

80.12.13.2
80.12.102.66
80.12.209.66
80.12.66.97

Vous êtes toujours là ? Alors vous vous demandez sans doute comment déclarer votre URL de backend... et nous avons des API pour cela :

  • 1 API pour souscrire aux SMS DR en déclarant votre endpoint, ou URL de callback
  • 1 API pour vérifier votre URL de callback
  • 1 API pour vous désinscrire des notifications SMS DR

API de souscription au SMS DR

Veuillez utiliser cette API lorsque votre backend est prêt à recevoir les SMS DR venant des serveurs Orange. Avant d'envoyer de vraies campagnes d'envoi de SMS, il est recommandé de tester unitairement les requêtes et la bonne réception des SMS DR.

Il faut déclarer votre URL de backend, comme par ex. https://{{dev_host}}/orange/smsdr.php. Note : vous ne pouvez déclarer qu'une seule URL qui sera utilisée pour toutes vos applications et tous les pays.

Exemple :

POST https://api.orange.com//smsmessaging/v1/outbound/tel%3A%2B4{{dev_phone_number}}/subscriptions HTTP/1.1
Authorization: Bearer {{access_token}}
Content-Type: application/json
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://{{dev_host}}/orange/smsdr.php"
        }
    }
}

Réponse typique d'Orange :

HTTP 201 OK
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://{{dev_host}}:443/orange/smsdr.php"
        },
        "resourceURL": "https://api.orange.com/smsmessaging/v1/outbound/subscriptions/{{subscription_id}}"
    }
}

Note : l'API de souscription au SMS DR retourne un unique {{subscription_id}} que vous devez enregistrer pour pouvoir vous désincrire plus tard, le cas échéant.

Vérification des paramètres pour SMS DR

Cette API vous permet de vérifier votre URL de callback pour les SMS DR, au moyen de ID de votre subscription {{subscription_id}}.

Exemple :

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
https://api.orange.com/smsmessaging/v1/outbound/subscriptions/{{subscription_id}} 

Réoponse typique d'Orange :

HTTP 200 OK
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://{{dev_host}}/orange/smsdr.php"
        },
        "resourceURL": "https://api.orange.com/smsmessaging/v1/outbound/subscriptions/{{subscription_id}}"
    }
}

Désinscription au SMS DR

Cette API vous permet de vous désinscrire des notifications de SMS DR. Exemple :

curl -X DELETE \
-H "Authorization: Bearer {{access_token}}" \
https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B{{dev_phone_number}}/subscriptions/{{subscription_id}} 

Réponse typique d'Orange :

204 No Content

Si vous avez oublié votre {{subscription_id}}, veuillez souscrire de nouveau, même avec une URL imaginaire, afin de recevoir un ID unique et de vous désinscrire.

Testez votre API

Vous pouvez copier et coller les commandes CURL dans votre Terminal sous Unix ou MacOS et votre ligne de commande sous Windows.

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)