SMS Niger
Engage with your users via SMS in Niger. Purchase SMS bundles with your Orange SIM card and get started in minutes.

version française (télécharger)

This document describes each step of the whole process to send SMS and access to your account, through the Orange SMS API.

The full SMS API reference is available in three parts:

  • SMS messaging, which allows the sending the SMS
  • SMS Admin, which provides SMS reporting
  • Receive in real-time the SMS DR (Delivery Receipt) on your own back-end

Terminology:

  • client: your application that will make Orange API calls
  • endpoint: the url to access, in REST, to a function of the API
  • header: a user defined HTTP header used to carry information in a REST call

Before starting

In order to be able to make calls to the Orange SMS API, you need credentials for your application: they are used by the backend platform to identify your application and thus to allow it to make calls to the SMS API. You get these credentials when you register your application on the Orange Partner Portal.

The method to get an access_token is described here.

Now, let's have some fun with the SMS API!

You are now ready to connect to the SMS API. Let's start easy with the send SMS API, then we'll see how to use the 3 APIs returning information about your account.

Do not forget to set the HTTP header Authorization, with as value, the concatenation of "Bearer " and the token you previously got.

  • How to get started with the SMS API ? Watch the tutorial.
  • How to integrate the SMS API ? Check out the webinar or read the article.

Send SMS

In order to send SMS from the API, please note that you need to buy first a SMS bundle. As Orange cares to ease your integration, you are able to buy a "Starter bundle" with some SMS at a very good price. Do note that this "Starter bundle" can be bought once per Orange Partner account or once per Orange phone number you will use for the payment. From your application, you just need some lines of codes to send the SMS to your customer. For this usage, please use the previously generated access token in the Authorization header and access this end point /smsmessaging/v1/outbound/{senderAddress}/requests, as below:

curl -X POST -H "Authorization: Bearer ThniC0...R0ckSaleS" 
-H "Content-Type: application/json" 
-d '{"outboundSMSMessageRequest":{"address": "tel:+225abcdefgh","senderAddress":"tel:+22500000000","outboundSMSTextMessage":{"message": "Hello World !"}}}' 
"https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B22500000000/requests"

Few important points here if you want to successfully send a SMS:

  • Be sure to set the same value of the SenderAddress in the end point {senderAddress} and in the JSON body
  • The {senderAddress} in the endpoint has to be url-encoded "tel:+22500000000" will be "tel%3A%2B22500000000"
  • Do not forget to set the "Content-Type: application/json" header
  • Do not forget to buy a SMS bundle from the "configure" button from your application dashboard

Please also note that on the client mobile, the sender name of your SMS will be automatically pushed by our SMS API. The sender name is linked to your Orange Partner account.

This request returns Headers and JSON data containing information about your well sent SMS ; otherwise you will get a HTTP error with more information about your error in the JSON data.

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api.orange.com/smsmessaging/v1/outbound/tel:+22500000000/requests/t1977324-0c1n-2403-n1c0-a1ec08071116
Content-Length: 12345
Date: Thu, 01 Avr 2015 02:38:38 GMT

{
    "outboundSMSMessageRequest":{
        "senderAddress":"tel:+22500000000",
        "senderName": "test",
        "outboundSMSTextMessage":{
            "message":"Hello World and beyond !"
        },
        "resourceURL":"https://api.orange.com/smsmessaging/v1/outbound/tel:+22500000000/requests/t1977324-0c1n-2403-n1c0-a1ec08071116"
    }
}

Note: The location Header as well as the resourceURL parameter from the json body is containing a URL with a ressourceId. In the above example, the ressourceId is t1977324-0c1n-2403-n1c0-a1ec08071116. If you want to use SMS Delivery Receipt (SMS DR), please retrieve and store this value as unique ID for your SMS MT. You will need it to correlate the proper SMS DR.

View your SMS balance

From your application, or inside your own administration zone, you may have the need to check and display how many SMS you can still send to your customers. For this usage, please use the previously generated access token in the Authorization header and access this end point /sms/admin/v1/contracts, as below:

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

This request returns JSON data containing information about your SMS balance and the expiration date.

{
    "partnerContracts":{
        "partnerId":"53laht-s1-3r0m-naht-3m0s3wa",
        "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 that you can add an optional parameter in this endpoint to filter on one country with /sms/admin/v1/contracts?country=CIV where CIV is the international 3 digits country code for "Côte d'Ivoire" (access all "ISO 3166 alpha 3" country code by clicking here).

View your SMS usage per application

From your application, or inside your own administration zone, you may have the need to track how many SMS has been sent per application. For this usage, please use the previously generated access token in the Authorization header and access this end point /sms/admin/v1/statistics, as below:

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

This request returns JSON data containing information about your SMS usage per application (and per country).

{
    "partnerStatistics":{
        "partnerId":"53laht-s1-3r0m-naht-3m0s3wa",
        "statistics":[
            {
                "service":"SMS_OCB",
                "serviceStatistics":[
                    {
                        "country":"CIV",
                        "countryStatistics":[
                            {
                                "applicationId":"45153daa87e...84e8e4ba",
                                "usage":153
                            },
                            {
                                "applicationId":"45153daa87e...4d735trf",
                                "usage":23
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

Note that you can add 2 optional parameters to the endpoint to filter on one country and/or with one dedicated application with /sms/admin/v1/statistics?country=CIV&appid=45153daa87e...4d738830f4e8e4ba where CIV is the international 3 digits country code for "Côte d'Ivoire" (access all "ISO 3166 alpha 3" country code by clicking here) and where appid is the application ID you can retrieve from your dashboard application.

View your purchase history

Last but not least for the account management API, you may also have the need to track all the purchased order you did on your account. For this usage, still use the previously generated access token in the Authorization header and access this end point /sms/admin/v1/purchaseorders, as below:

curl -X GET -H "Authorization: Bearer ThniC0...R0ckSaleS" "https://api.orange.com/sms/admin/v1/purchaseorders"

This request returns JSON data containing information about your SMS bundle(s) purchase history.

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

Like the "contracts" API, you may filter to display only the purchase orders for one particular country by using the endpoint with /sms/admin/v1/purchaseorders?country=CIV where CIV is the international 3 digits country code for "Côte d'Ivoire" (access all "ISO 3166 alpha 3" country code by clicking here).

Everything about SMS Delivery Receipt

Each SMS MT (Mobile Terminated) will trigger a SMS DR (Delivery Receipt) in the next 24 hours. First of all, you need to create an endpoint on your own server/back-end in order to receive Orange requests. The back-end URL:

  • has to be secured and should start with https://
  • should be accessible over internet (on PORT 443 only!)
  • has to return a HTTP 200 OK in response of the Orange request in order to acknowledge it

Example: SMS DR Request from Orange to Partner's SMS DR endpoint

POST https://[PARTNER_HOST]:443/orange/smsdr.php HTTP/1.1
Content-Type: application/json
{
    "deliveryInfoNotification":{
        "callbackData":"t1977324-0c1n-2403-n1c0-a1ec08071116",
        "deliveryInfo":{
            "address":"tel:+22500000000",
            "deliveryStatus":"DeliveredToTerminal"
        }
    }
}

Example: Response by the partner

HTTP/1.1 200 OK

In the json body of Orange request, your back-end server is receiving 3 important information:

  • callbackData: the unique ID of your previously well sent SMS MT that you will have to use to correlate the corresponding SMS MT
  • address: the MSISDN of your previously well sent SMS MT
  • deliveryStatus: the status of the SMS DR

deliveryStatus may have different possible values: Value | Description ------------------- | ------------------------------------------------------------------------------------------------------------------------ DeliveredToNetwork | Successful delivery to network. DeliveryUncertain | Delivery status unknown: e.g. because it was handed off to another network. DeliveryImpossible | Unsuccessful delivery; the message could not be delivered before it expired. MessageWaiting | The message is still queued for delivery. This is a temporary state, pending transition to one of the preceding states. DeliveredToTerminal | Successful delivered to Terminal

Important note about SMS DR Status

In general, SMS DR information is not 100% reliable. In case you get DeliveredToTerminal, you can rely on this information. But behind a DeliveryImpossible status, your SMS can still be well delivered (e.g. if a phone is not reaching any network or out of battery during more than 24 hours) ; or you get this status if you send a SMS to a land number or a number that is not used anymore and that has been de-activated. Orange will not refound any SMS even if you are getting DeliveryImpossible status.

Find below a basic PHP code in order to retrieve the SMS DR on your server

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

In case of your back-end server is IP protected, please allow requests from 80.12.13.2

Still reading ? Now, you probably wonder how to declare your back-end URL to Orange. This is a good question! And we have APIs for that of course:

  • 1 API to subscribe to SMS DR by providing your secured callback endpoint. You can use multiple time this subscribe API. The last URL provided will replace the URL set in Orange system.
  • 1 API to check the callback URL you have set previously
  • 1 API to unsubscribe to SMS DR

Subscription API

Please use this API once your back-end server is ready to receive SMS DR requests from Orange server. Before sending real SMS MT, in order to test your SMS DR endpoint, we strongly advice to do some unitary testing by sending directly POST requests to it and see how it reacts. Once you think you are OK, you can start sending real SMS MT and check the good delivery of it (make sure that your test number is on the network, it will help speeding up your testing phase).

So, in order to declare your back-end url, let say https://[PARTNER_HOST]/orange/smsdr.php, you still need to use your previously generated Token in order to send correctly the request. Note that you can only declare 1 endpoint ; this URL will be used for all your applications, whatever the country you are sending your SMS MT.

Example: Your request to subscribe

POST https://api.orange.com//smsmessaging/v1/outbound/tel%3A%2B400/subscriptions HTTP/1.1
Authorization: Bearer ThniC0...R0ckSaleS
Content-Type: application/json
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://[PARTNER_HOST]/orange/smsdr.php" 
        }
    }
}

Orange response will be

HTTP 201 OK
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://[PARTNER_HOST]:443/orange/smsdr.php"
        },
        "resourceURL": "https://api.orange.com/smsmessaging/v1/outbound/subscriptions/56e19nt197703244e46181c8"
    }
}

Note that Orange SMS DR subscription API is returning a unique ID (56e19nt197703244e46181c8 in the above example). You need to keep somewhere this ID in order to be able to unsubscribe later on.

Check SMS DR subscription API

This API allow you to check the callback URL entered in Orange system for the SMS DR requests. In order to call this API, you need to enter your own subscription ID {SubID}. In our previous example, you need to enter 56e19nt197703244e46181c8 instead of {SubID}.

Example: Your request to check your subscription

GET https://api.orange.com/smsmessaging/v1/outbound/subscriptions/{SubID} HTTP/1.1
Authorization: Bearer ThniC0...R0ckSaleS
Content-Type: application/json

Orange response will be

HTTP 200 OK
{
    "deliveryReceiptSubscription": {
        "callbackReference": {
            "notifyURL": "https://[PARTNER_HOST]/orange/smsdr.php"
        },
        "resourceURL": "https://api.orange.com/smsmessaging/v1/outbound/subscriptions/56e19nt197703244e46181c8"
    }
}

Unsubscription SMS DR API

This API allow you to stop the SMS DR requests to your endpoint. Like the previous API, you need to enter your own subscription ID {SubID}. Please also note that the method to call the API is DELETE.

Example: Your request to unsubscribe

DELETE https://api.orange.com/smsmessaging/v1/outbound/tel%3A%2B400/subscriptions/{SubID} HTTP/1.1
Authorization: Bearer ThniC0...R0ckSaleS
Content-Type: application/json

Orange response will be

204 No Content

In case you totaly forgot your {subID}: subscribe again (even with a fake URL), retrieve the generated unique ID, then unsubscribe again.

Firefox RESTClient samples

If you are not confident with CURL queries, and if you want to test our APIs, you can also use the Firefox "RESTClient" extension (download here with your Firefox browser). Once "RESTClient" installed, you can download and unzip a backup of all the SMS API requests here. From your RESTClient plugin, from the 'Favorite Requests' menu, please Import the .json file that you have previously unzipped on your computer. Once successfully imported, hit "F5" key or click on your Firefox refresh icon, and go back to the Favorite Requests' menu. All the SMS API requests will be there.

Please note that all the user information have been deleted from the .json file, it will be up to you to replace them with your own values (either with notepad before importing, or directly in the RESTClient interface). The user information values are:

  • enter_your_consumer_key_here: for the oAuth/token API, you need to enter your consumer_key (please refer to the "authorization (OAuth2)" documentation to be able to generate a token
  • enter_your_token_here: each API for SMS sending or SMS Admin requests a valid token for authentication, please enter your generated token instead
  • +225xxxxxxxx: replace the destination address (only for the send SMS API) where you want to send your message

Document history

Doc VersionDateChanges
1.218-may-2016SMS Delivery Receipt
1.118-nov-2015Added: link to authentication document
1.007-jul-2015First release