Skip to content

Run locally

If you are an absolute beginner please read the prerequisites first.

First let's create our virtual environment. We will be using Ubuntu 18.04 in this tutorial.

onem@local:~$ mkvirtualenv todo
...  # skipped for brevity
(todo) onem@local:~$ 

The above will create the virtual environment and activate it at the same time.

Download source code

Clone the project from

(todo) onem@local:~$ git clone None


We first need to install the dependencies and create the database.

(todo) onem@local:~$ cd django-onem-todo
(todo) onem@local:~$ pip install -r requirements.txt
(todo) onem@local:~$ python migrate

Start the server

(todo) onem@local:~$ python runserver

The above command will run the server locally at

If you try to access that link you will get a 403 error forbidden response, which is totally fine, since the server is looking into the HTTP headers for specific information sent by ONEm platform.

Expose the server publicly

Since our server is now running on your local interface, ONEm platform cannot reach it. But we can work around this by using ngrok.

Open a new terminal and start up ngrok on localhost port 8000.

onem@local:~$ ngrok http 8000

The above command will start ngrok tool, which is basically creating a VPN tunnel so our webserver can be publicly reachable.

The output should be something like:

Session Status                online
Session Expires               7 hours, 59 minutes
Update                        update available (version 2.3.34, Ctrl-U to update)
Version                       2.3.30
Region                        United States (us)
Web Interface       
Forwarding           -> http://localhost:8000
Forwarding           -> http://localhost:8000

The important bit here is the link. We will be using this as our callback url when we will register our app on ONEm developer portal.

Register the application

To register your application please open ONEm Developer Portal and register for a free account.

Once that is done, you will have an option to create an app. Hit that button and place as the callback url.

That is it. We can now access the application by placing a hashtag in front of the name.

Run it

In the developer portal there is a Test Client section. This is a phone simulator from where you can test the app.

Head on to the test client and send #name-of-your-app. At this point ONEm will request the callback url we've set previously, so if you check the ngrok logs you will see the request there.

HTTP Requests
GET /                          200 OK   

In the test client you can see the below response:

A New todo
B Done(0)
--Reply A-B

*the name of your app will be different, as chosen in the developer portal

The above sms response is rendered based on the HTTP json response returned by our / url.

If we look in the todo.todo.views we can see that HomeView view which is handling the / route is basically returning a Menu json object.

Every menu item contains a callback path, as described in the json structure here and once the user selects one of the menu items, an HTTP request will be made towards that callback path, a new json structure is returned by our web server, so a different sms response is presented to the user.