Django app to add support for Orange API SMS-MO, SMS-MT/DR

orange, api, sms
pip install orangeapisms==0.28



Django app to add support for Orange API SMS-MO and SMS-MT (with DR)


  • pip install orangeapisms
  • Edit your file and add:
INSTALLED_APPS = list(INSTALLED_APPS) + ['orangeapisms', 'django_forms_bootstrap']
  • Configure your orangeapi.json file (place it next to your file):
    "handler_module": "myapp.orange_handler",
    "use_db": true,
    "sender_address": "+22300000000",
    "sender_name": "POTUS",
    "client_id": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "client_secret": "xxxxxxxxxxxxxxxx",
    "enable_tester": true,
    "default_sender_name": "sender_address"
  • Setup Database with ./ migrate

That's it ! Test it by accessing /oapi/ and playing with the tester.

client_id: Your Client ID (mandatory)
client_secret: Your Client Secret (mandatory)
handler_module: python path to your module handling messages (mandatory)
use_db: whether to store SMS in DB (SMSMessage Model)
smsmt_url: URL of your API (might change depending on your plan)
oauth_url: OAuth URL for Orange API
sender_address: Your subscribed phone number
sender_name: Your custom sender name (can be number or string)
enable_tester: To enable tester & logs WebUI on /oapi/
default_sender_name: What to use as default sender name
send_async: whether to deffer SMS sending to celery
celery_module: python path to your celery tasks module
country: ISO 3166-1 code for your country (used for balance checking)
fix_msisdn: whether to fix SMS-MT destination without prefix
country_prefix: MSISDN numeric prefix for your country (to fix SMS-MT without prefix)


After installation (previous step), you are able to send & receive individual SMS. To automatically process incoming SMS, you will have to customise the handler module which you specified in ORANGE_API['handler_module'].

The module would call three different functions based on events:

  • smsmo(message) on an incoming SMS-MO
  • smsmt(message) on an outgoing (sent by you) SMS-MT
  • smsdr(message) on an incoming delivery-receipt notification. The passed message is the SMS-MT which received the DR.

Sample handler module:

import datetime
import logging

from orangeapisms.utils import send_sms
from myapp.models import UserModel

logger = logging.getLogger(__name__)

def handle_smsmo(message):"Received an SMS-MO: {}".format(message))

    def register_user(message, keyword, text):
        # break-down the formatted SMS into variables
            name, sex, dob = text.split()
            return message.reply('Invalid format')

        # valid user entries
        if sex not in ['m', 'f']:
            return message.reply('Unable to understand sex')

        # reuse input into different data structure
            d = dob.split('-')
            birthdate = datetime.datetime(d[3], d[2], d[1])
            return message.reply('Unable to understand date of birth')

        # make use of the data including message metadata
        user = UserModel.objects.create(
            name=name, sex=sex, dob=birthdate,

        return message.reply("Congratulations, you're registered as #{}"

    def broadcast_to_users(message, keyword, text):
        # loop on all Users in DB
        for user in UserModel.objects.all():
            # send a custom message to that user
            send_sms(, "Hey {u}, {c}".format(, c=text))

    keywords = {
        'register': register_user,
        'broadcast': broadcast_to_users,

    # find the proper keyword
    keyword, text = message.content.split(' ', 1)
    if keyword in keywords.keys():
        return keywords.get(keyword)(message, keyword, text.strip().lower())

    # fallback on error
    return message.reply('Unknown request')

def handle_smsmt(message):"Sent an SMS-MT: {}".format(message))

def handle_smsdr(message):"Received an SMS-DR: {}".format(message))

Using a broker to send SMS-MT

By default, SMS-MT are sent synchronously meaning your request is stalled until the API call is complete.

If you need to send multiple SMS-MT while not blocking the request thread, you will want to defer sending to a broker.

This library integrates easily with celery so you can do just that in a breeze.

To use Asynchronous SMS-MT sending, you will need to :

  • Install and configure celery onto your project (see instructions bellow if needed)
  • Edit your to include the following options
# wether to send asynchronously or not
'send_async': True,
# python path of your celery module containing the task
'celery_module': 'myproject.celery'
  • Add a custom task to your celery module
def submit_sms_mt_request_task(payload, message):
    from orangeapisms.utils import do_submit_sms_mt_request
    return do_submit_sms_mt_request(payload, message)

That's it. Now every SMS-MT will be deferred to celery and processed by your broker.

Launch a celery worker to test it!

Basic celery configuration

If you are not familiar with celery and want to quickly test the async feature, follow this steps:

  • Install redis on your computer and start it
sudo apt-get install redis
service redis start
  • Install celery and redis with `pip install celery redis`
  • Add the celery configuration to your
BROKER_URL = 'redis://localhost:6379/0'
CELERY_RESULT_BACKEND = 'redis://localhost:6379/0'
  • Create a module in your project for celery:
import os

from celery import Celery

os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'project.settings')
app = Celery('project')

def submit_sms_mt_request_task(payload, message):
    from orangeapisms.utils import do_submit_sms_mt_request
    return do_submit_sms_mt_request(payload, message)
  • Launch a worker
celery -A project worker -l info