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.

note: the token will last 7776000 seconds, i.e. 90 days. After this period, you'll get an error and should request anotjer 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.

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:

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:

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:

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.

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:

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.

As an example, please find below a basic PHP code to retrieve the SMS DR on your backend:

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.