SMS Mali - Business

2.0

• 3.0 (current)
• 2.0 (deprecated)

With Orange APIs and a few lines of code, you can easily send SMS, receive delivery receipts in realtime, receive SMS on your backend and manage your account as admin.

Before sending SMS, you first need to get credentials for your application on this portal, specify which countries you'd like to address and buy relevant credits: SMS bundle(s).

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 Developer account or once per Orange phone number you will use for the payment.

Let's assume you declared your application with relevant SMS API(s) and bought your bundle, we can start now.

Authentication

As credentials, you just need your app's {{authorization_header}} (available from your app page on this portal) to request a token using the OAuth 2.0 standard POST method, as follows:

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: -d flag implies standard encoding: application/x-www-form-urlencoded

You then receive JSON data from which you can parse your {{access_token}}:

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

note: the token will last 3600 seconds, i.e. 1 hour. After this period, you'll get an error and should request another token, the same way.

For further details and potential error codes, please check the detailed guide.

Send SMS

As stated above, please note that you first need to buy a SMS bundle from your app configuration page on this portal.

To send a SMS to a {{recipient_phone_number}}, you just need to use your {{access_token}} and indicate your {{dev_phone_number}} as senderAddress and in the body and endpoint, with your country code but without + or 00 prefix.

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"

Your dev_phone_number must appear twice: in the body and in the url of the call, where tel:+ is url-encoded: tel%3A%2B

Examples of SMS sender addresses per country, with reminders of the related ISO-3166 alpha 3 country codes:

Please also note that on the client mobile, the sender name of your SMS will be automatically pushed by our SMS API backend. The sender name is linked to your Orange Developer 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:+{{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: if the sender name used is not on the list of provided sender names on this platform, you will get an error: 400 requestError. If the Service Provider has not a whitelist, the default sender name will be used.

You get a {{resource_id}} as a unique ID you need to store if you want to correlate the proper Delivery Receipt (DR). {{resource_id}} is a string with the following typical format: xxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Note: You cannot send more than 5 SMS per second.

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 {{access_token}}" \
"https://api.orange.com/sms/admin/v1/contracts"

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

{
    "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: you can add an optional parameter in this endpoint to filter on one country with: /sms/admin/v1/contracts?country={{country_code}} where {{country_code}} is the international 3-digit country code, e.g. CIV for Côte d'Ivoire (Ivory Coast). Access all "ISO 3166 alpha 3" country codes are listed here.

Note: {{partner_id}} typically is your developer email.

View your SMS usage

From your application or inside your own administration zone, you may need to track how many SMS has been sent per application and/or country. For this usage, please use your {{access_token}} in the authorization header and access the end point: /sms/admin/v1/statistics, as follows:

curl -X GET \
-H "Authorization: Bearer {{access_token}}" \
"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":"{{partner_id}}",
        "statistics":[
            {
                "service":"SMS_OCB",
                "serviceStatistics":[
                    {
                        "country":"CIV",
                        "countryStatistics":[
                            {
                                "applicationId":"45153daa87e...84e8e4ba",
                                "usage":153
                            },
                            {
                                "applicationId":"45153daa87e...4d735trf",
                                "usage":23
                            }
                        ]
                    }
                ]
            }
        ]
    }
}

You can add 2 optional parameters to the endpoint to filter by country and/or application: /sms/admin/v1/statistics?country={{country_code}}&appid={{app_id}}

• {{country_code}} is the international 3-digit country code, e.g. CIV for Côte d'Ivoire. Access all "ISO 3166 alpha 3" country codes: here
• {{app_id}} is the application ID you can retrieve from your dashboard of this portal.

View your purchase history

Last but not least for the account management API, you may also need to track all the purchased orders you did with your account. For this, use your {{access_token}} in the authorization header and access the point /sms/admin/v1/purchaseorders, as follows:

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

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

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

As with "contracts" API, you may filter per country with an optional endpoint parameter: /sms/admin/v1/purchaseorders?country={{country_code}} where {{country_code}} is the international 3-digit country code, e.g. CIV for Côte d'Ivoire. Access all "ISO 3166 alpha 3" country codes here.

All about SMS Delivery Receipt

Each SMS sent 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 and manage this receipt.

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 order to acknowledge the receipt

Example: SMS DR Request from Orange to your SMS backend and DR management endpoint

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

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:

• {{resource_id}}: the unique ID of your previously well sent SMS that you will have to use to correlate the corresponding SMS
• {{recipient_phone_number}}: the MSISDN of your previously well sent SMS
• {{delivery_status}}: the status of the SMS DR

{{delivery_status}} may have different possible values:

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.

As an example, please find below a basic PHP code to retrieve the SMS DR on your 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
        // ..
    }
?>

In case of your back-end server is IP protected, please allow (white-list) requests from the following IP addresses:

80.12.13.2
80.12.102.66
80.12.209.66
80.12.66.97

Still reading? Now, you probably wonder how to declare your back-end URL to Orange... 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, 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 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://{{dev_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%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"
        }
    }
}

Orange response will be

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: the Orange SMS DR subscription API is returning a unique {{subscription_id}} that 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 {{subscription_id}}.

Example: Your request to check your subscription

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

Orange response will be

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

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

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

Orange response will be

204 No Content

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

Live API Testing

You can copy/paste the CURL commands right in your Terminal session on Unix, Mac and Windows desktop computer.

You also can benefit from a Postman collection, named Orange SMS MEA that we prepared for you, with essential calls and environment variables.

The collection includes a set of 5 essential API requests:

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

The related environment includes the following variables:

• authentication_header: credentials for your app, to copy from this portal and paste in current value field, as a prerequisite to any call/test
• access_token: parsed from the Authentication POST reply
• dev_phone_number: your phone number to paste in value field
• recipient: your test recipient's phone number to paste in value field
• partner_id: parsed from API call reply
• resource_id: parsed from API call reply

Note: above parsing is automatically managed by the embedded javascript in the collection file ("test" tab).