A Cinema Movie Booking System Using U.S.S.D. A.P.I. and SMS shortcode to send ticket details

Introduction

The project looks into how you can use Africa’s Talking U.S.S.D. and SMS short code to create a Cinema Movie Booking System, this can be done when a cinema would want its customers to make bookings via U.S.S.D. and get ticket confirmation details and codes via an S.M.S. Short Code.

This will allow cinemas to have an efficient way for allowing their clients to book movie screening, the system is also modified to send SMS short codes to the clients informing them that the booking was successful as well as a reference code which can be modified to include a receipt upon payment of the fees.  

Intended audience: Who the article is for

This article targets python/Django developers who would want to build a web based movie booking system, that allows for clients to book movie screening in advance and can extend this project to use Africa’s Talking Payment A.P.I. to pay for the movie.

Case Study: What the article is going to cover

The project will display three use cases, the first being – building a web based Django cinema bus booking system, the second being – building an A.P.I. that will interact with Africa’s Talking U.S.S.D. A.P.I and the third being – building an A.P.I. that will interact with Africa’s Talking short code A.P.I.

The application is built using python programming language in Django Framework.

Requirements:

  1. Some knowledge of Python and Django
  2. A website domain name for your Django project
  3. Africa’s Talking A.P.I. Key
  4. Africa’s Talking U.S.S.D. A.P.I.
  5. Africa’s Talking Short Code A.P.I.

Acquiring a website domain name for your Django project

The reason we need a website domain for the Django project is because, the U.S.S.D. A.P.I. requires us to set the URL of the Django web app that’s hosting the A.P.I. to be used as a call back when a user initiates the U.S.S.D. call.

Since the Django project will be developed and hosted on our local computer it is only accessible via the URL http://127.0.0.1:8000, with this URL the Django project in your local computer cannot be accessed on the internet. So we need to find a way for our Django project A.P.I. to be accessible via the web, to do so we will use a free downloadable software called Ngrok. i.e. http://127.0.0.1:8000 is the same as http:// localhost:8000 Ngrok is an application that creates a dummy http URL that we will use to map to http://127.0.0.1:8000 (where the Django project is running) e.g. Ngrok could create a dummy URL http://231fd19e6a93.ngrok.io and map it to http://127.0.0.1:8000, so when any user, online enters the dummy URL on their browser they will be able to view the Django project and it’s A.P.I. and it can also be accessed via Africa’s Talking online U.S.S.D. A.P.I.

Steps:

  1. Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup, on this page they you will be prompted to sign up to download the application, go ahead and do so.
  2. After signing up you will see the page below:
  1. Download and start/run the application
  2. After running the Ngrok application you will see the terminal below:
  1. Go back to the Ngrok web page that is displayed above and navigate to the section labeled “Connect your account”
  2. Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal, this is so that the dummy URL you will create does not expire after a short period, after which you will have to create another dummy URL
  3. Since we want to map the localhost port 8000 to a dummy URL go back to the Ngrok terminal and type the command “ngrok http 8000”, this will open the ngrok shell below with the name of the newly created dummy http URL e.g. http://231fd19e6a93.ngrok.io that maps -> to the http://localhost:8000 port where your Django project will be running from

8. You will need the generated dummy ngrok URL while creating Africa’s Talking U.S.S.D. A.P.I.

Generating Africa’s Talking A.P.I. Key:

  1. Navigate to this URL: https://account.africastalking.com/apps/sandbox/settings/key you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
  2. While on this page enter your Africa’s talking account password and click on the button labeled “Generate”
  3. Your API key will be generated and displayed to you
  4. Copy and paste it in a Notepad or somewhere you will remember

Configure your Africa’s Talking SMS Short code:

  1. Navigate to this URL: https://account.africastalking.com/apps/sandbox/sms/shortcodes you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
  2. While on that page click on the link labeled “create a short code” to create a USSD code
  3. Enter a unique dummy short code e.g. 12435

Creating Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
  2. While on that page click on the link labeled “create a channel” to create a USSD code
  3. You will be prompted with the pop up below:
  1. Enter a unique dummy channel e.g. 12345
  2. Your U.S.S.D. Code is now e.g. *384*12345#
  3. In the callback URL paste the ngrok http URL you created above, after appending “/api/ussd_callback/” at the end of the URL e.g. http://231fd19e6a93.ngrok.io/api/ussd_callback/ we will create this “/api/ussd_callback/” A.P.I. later on in the Django project.
  4. Click on Create Channel

Creating a Django Project

  1. From your terminal navigate to the folder/location your project is to reside
  2. We will create a Django project called “cinemabooking”, type the command: django-admin startproject cinemabooking
  3. From the terminal navigate into the created project folder, where you will create and activate your project’s virtual environment by typing in the terminal the command “python –m venv venv”
  4. In windows, type “venv\Scripts\activate” in the terminal
  5. In Mac/Linux, type ”source venv/bin/activate” in the terminal
  6. After your virtual environment has been activated, run the code below in the terminal to install the following python packages
    • “pip install requests” : python package used in managing HTTP requests
    • “pip install Pillow”: python package to be used in managing images
    • “pip install djangorestframework”: python package used in creating REST A.P.I.s
    • “pip install django” : python package to be used in building the web app
    • “pip install django-crispy-forms”  : to be used rendering bootstrap styles in HTML templates
  7. Create your first Django app by typing in the terminal the command: “python manage.py startapp cinema”
  8. Create a SQLite database that will used by the project by typing in the terminal the command: “python manage.py makemigrations”
  9. Apply database changes by typing in the terminal the command: “python manage.py migrate”
  10. Start your server by typing on the terminal the command: “python manage.py runserver”
  11. If the server starts successfully there should be a webpage up and running on the location: http://127.0.0.1:8000
  12. While in the terminal type Ctrl+C to stop the server
  13. Everything from now on will be performed inside this python activated environment

We are stopping the server so that we can create the database tables first and then apply the changes before restarting the server

Creating Project CSS File

  1. Open the Django project folder your code editor
  2. Open the “cinema” app folder
  3. In the “cinema” app folder, create a folder labeled “static”
  4. Inside the created “static” folder create another folder labeled “cinema”
  5. Inside the “cinema” folder just created inside the “static” folder, create a css file labeled “main.css”
  6. Copy the code below into the “main.css” file

Configure Django Project Settings

  1. Open your Django project folder: “cinemabooking”
  2. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “cinema” app folder
  3. Inside this folder is a python file labeled “settings.py”
  4. Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file
  5. Inside the ALLOWED_HOSTS enter the ngrok URL created as well as the localhost URL, this is a security measure by Django to ensure that the web app can only be accessed via the set URLs. Below is an example of how to do so:
  1. Inside the “settings.py” file, locate the variable INSTALLED_APPS
  2. The variable installed_apps is a list where you will register the apps we just created
  3. Insert the code below inside the list:

9. We also need to register the Django crispy form python package that we will use to beautify our HTML pages, inside the INSTALLED_APPS python list paste the code below:

10. We also need to register the Django rest framework app that we will use to manage and create the project A.P.I.s, inside the INSTALLED_APPS python list paste the code below:

11. We also need to inform crispy to use bootstrap 4 in its rendering of HTML elements, to do this paste the code below at the end/bottom of the settings.py file:

  1. Data is sent from Africa’s Talking U.S.S.D. A.P.I. to our Django project A.P.I. in the form “Content-Type: application/x-www-form-URLencoded”. We have to inform our Django A.P.I. to expect data to be sent to it in this format as the default format Django rest framework A.P.I. expects data is JSON format.
  2. Data should also be sent back from our Django A.P.I. to Africa’s Talking USSD A.P.I. in a string format or as a plain text. Django rest framework A.P.I. sends data out in JSON format by default, we have to inform or configure our A.P.I. to send data in plain text and not JSON format.
  3. To perform the above actions paste the code below at the bottom or end of the settings.py file:

Creating Database Tables

  1. Open your Django project folder in your code editor
  2. We now create the database tables related to the “cinemas” app we created, which are:

Movies Table Logic

This table will hold the names of the movies screened in the cinema, a brief description, URL to the trailer video and a photo of the movie. It will have the following fields:

name –This column will hold the name of the movie

description –This column will hold the a brief description of the movie

trailer_URL –This column will hold the name a URL trailer of the movie

length –This column will hold the length of the movie

__str__ –This is a method in the class “Movies” class we will create that will be responsible for returning back the string representation of objects or table records created in the Movies table. The string representation method will return is the name of the movie

Movies Image Table Logic

This table will hold the names of the movies screened in the cinema, a brief description, URL to the trailer video and a photo of the movie. It will have the following fields:

movie –This column will create a relationship with the movie to be screened

image – The promotional image of the movie

__str__ –This is a method in the class “MoviesImage” class we will create that will be responsible for returning back the string representation of objects or table records created in the Movies table. The string representation method will return is the name of the movie appended with the word “Image”

Movies Dates Table Logic

This table will hold the dates the movies are screened and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

movie –This column will create a relationship with the movie to be screened

dates – The dates the movie will be screened

__str__ –This is a method in the class “MoviesDates” class we will create that will be responsible for returning back the string representation of objects or table records created in the “MoviesDates” table. The string representation method will return is the name of where the movie and screening date

Movies Date Times Table Logic

This table will hold the time when each or a specific movie will be screened on a particular date and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

movies_dates – The date a particular movie will be screened

start_time – The time the movie starts

end_time – The time the movie ends

__str__ – This is a method in the class “MoviesDateTimes” class we will create that will be responsible for returning back the string representation of objects or table records created in the “MoviesDateTimes” table. The string representation method will return is the movie name, the screening date and the screening times in that day or date.

Movie Bookings Table Logic

This table will hold the movie bookings made, the phone number of the client who made the booking and will inherit from the built in Django “models.Model” class which is used to convert a python class to a database table. It will have the following fields:

movies_date_times – The specific movie date and time booked

phone_number – The client’s phone number

booking_code – The unique reference code generated

__str__ – This is a method in the class “MovieBookings” class we will create that will be responsible for returning back the string representation of objects or table records created in the “MovieBookings” table. The string representation method will return is the “MoviesDateTimes” object.

To create the above “cinema” tables in your project folder, navigate into the “cinema” folder and open a file labeled “models.py” and paste the code below:

Apply Database Changes

  1. In your terminal ensure you have activate your project’s virtual environment
  2. While in your projects activated virtual environment in your terminal
  3. Create database changes to be made by typing in the terminal the command: python manage.py makemigrations
  4. Apply database changes by typing in the terminal the command: python manage.py migrate

Create Image Creation and Upload Forms

These are the forms used to render user data onto their profile pages

  1. Open the “cinema” app folder
  2. Locate/create a python filed labeled “forms.py”
  3. Paste the code below:

Creating your business logic for Cinema App

We will now create the business logic in the “views.py” file located in the “cinema” app folder. Below is how to do so:

  1. Open the “cinema” app folder
  2. Locate a python file labeled “views.py”
  3. Paste the code below

Views Code Logic

We start by importing the following methods:

  • Reverse – This method is used to return the URL representation of python URL pattern path name
  • Render – This method is used to return a HTML page to the user
  • Redirect – This method is used to redirect the user back to the URL passed to it as argument
  • CreateView – This is a Django built in class that can be used to create a database table entry by associating it with another class
  • UpdateView– This is a Django built in class that can be used to update a database table entry by associating it with another class
  • ListView – This is a Django built in class that can be used to return a list of records from a specified database table, hence converting the class inheriting from this class to a list view to be used on a HTML page
  • DeleteView – This is a Django built in class that can be used to delete a database record entry by associating it with another class, via inheriting from this class
  • Movies, MoviesDates, MoviesDateTimes, MovieBookings and MoviesImage – The four cinema database tables or models we created
  • MoviesImageForm – The form we created to use in uploading movie promotional images
  • messages – This is a Django built in method that can be used to send pop up messages from your views to the HTML pages

We now build the views/functions or methods below:

  • Home – This is a method or function view that accepts a web request and returns back the index HTML page render
  • Movies Create View – This is a class based view or a class that inherits its functionalities from django’s built in “CreateView” class. In this class we have to specify the model or database table the class will work with which is the “Movies”, the fields it’s to work with which are the ‘name’, ‘description’, ‘length’ and ‘trailer_url’ and the template that will render the data/form.

The class will also override its super class method “get_context_data”, what this method does, is that it allow us to get access to the data that will be passed to the template, before it’s sent to the template for rendering, the data is passed as a context object. After getting access to the context we add a new object variable with a value in it and return the context back.

We also override a super class method called “get_success_URL” that will be used to return the URL page a user is to be redirected to after they successfully create a destination in the database.

  • Movies List View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “ListView” class. In this class we have to specify the model or database table the class will work with which is the “Movies” and the template that will render the data.

The class will also override its super class method “get_context_data”, so as to allow us to get access to the data that will be passed to the template.

  • Movies Delete View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “DeleteView” class. In this class we have to specify the model or database table the class will work with which is the “Movies”, set a success URL which is the URL a user is to be redirected to after successful data deletion and the template that will render the data.

The class will also override its super class method “get_context_data”, so as to allow us to get access to the data that will be passed to the template.

  • Movies Update View – This is a class based view or a class that inherits its functionalities from another class view, in this case django’s built in “UpdateView” class. In this class we have to specify the model or database table the class will work with which is the “Movies”, the fields it’s to work with, which is the ‘name’ field, the template that will render the data/form.

The class will also override its super class method “get_context_data”, so as to allow us to get access to the data that will be passed to the template.

The above views will also be replicated in the creation of the MoviesDates, MoviesDateTimes and MovieBookings views.

  • movies_image_update – This is a view responsible for updating and uploading a movie’s promotional image using the “MoviesImageForm”

Creating the Django Project A.P.I.

This is the A.P.I. that will interact with Africa’s Talking U.S.S.D. A.P.I.

OTP Code Generator Implementation

  1. Open the “cinema” app folder
  2. Create a python filed labeled “generate_code.py”

Code Generator Logic

We will import the string and random modules, for manipulating strings and creating random choices respectively. The defined method “get_code” returns the random string, we first set the length of the random string. The String will be a concatenation of uppercase letters and numbers that will all total to six and be joined together to form a single six character string

  1. Paste the code below

Send Message Logic

You will need to import the requests library/module, this is a HTTP library used to send POST, GET, PUT etc. requests to APIs or websites to retrieve information.

We will also define a send method that takes two parameters, the phone number and message to send, we are providing the message with a default value here. From Africa’s Talking documentation the Short Code API expects a Payload and Header.

The Payload takes:

  • Username: Since we are running a test, we will use the sandbox username
  • To: the phone number we are sending the message to, I am using an “F-String”, this is a python string syntax that allows one to include python variables in the string
  • From: This is the short code the message is to be sent from, assuming you created one in Africa’s Talking developer page

The header takes two standard parameters “Accept” and “Content-Type”, the parameter that will need to be edited is the “apiKey”, this is the API key that was generated on your developer dashboard

Once the request is executed with the payload and headers, it returns a JSON response, from this response we will retrieve the data inside the JSON object “SMSMessageData”, we will then retrieve the data inside the JSON Object “Recipients” which is a list, we then access the first data of the list which contains a JSON Object “status”, that informs us if the message was sent successfully, which is what we return once the send method is executed.

  1. Paste the code below
  2. Enter your short code and A.P.I. key in the appropriate fields

Integrating Africa’s Talking U.S.S.D. A.P.I.

Steps:

  1. Inside your Django project folder: “cinemabooking”
  2. Create a folder called “api” which will be in the same directory as your “cinema” app folder
  3. Inside this ”api” folder create the following files:
    • __init__.py –  an empty python file to inform Django that “api” folder is a python package
    • renders.py – a python file that will be used to inform Django rest framework how to render or send data back to Africa’s Talking U.S.S.D. A.P.I. below is the code to paste inside this file:
    • URLs.py – a python file that will be used to map the Django project A.P.I. inside the views.py file to a URL that will be accessed by the Africa’s Talking U.S.S.D. A.P.I. below is the code to paste inside this file:
    • views.py – a python file that will hold the A.P.I. method that is responsible for sending back data below is the code to paste inside this file:

Creating “Cinema” HTML Templates

  1. On these HTML templates is where the different cinema data will be displayed
  2. We will start by creating HTML templates related to the “cinema” app we created, which are:
    • index.html – The default home page for the web app with brief instructions on how the web app works
    • base.html – This is the page that will be inherited/extended by all other HTML template pages
    • confirm_delete.html – This is the page to be used for asking a user to confirm that they want to delete a specific data record
    • movies_detail.html – This page will be used to display the details of the movie to be screened
    • movies_list.html – This page will be used to display a list of movies
    • movies_image_details.html – This page will be used to display a movie’s promotional image
    • movie_bookings_detail.html – This page will be used to display the details a movie booking made
    • movie_bookings_list.html – This page will be used to display a list of movie bookings made
    • movie_dates_detail.html – This page will be used to display the details of a specific date a movie has been set for screening
    • movie_dates_list.html – This page will be used to display a list of the dates movies have been set for screening
    • movie_date_times_detail.html – This page will be used to display the details of the start and end times in a date a movie will be screened
    • movie_date_times_list.html – This page will be used to display a list of start and end times in dates all movies will be screened
  3. To create the above “cinema” HTML templates do the following:
    • In your project folder navigate into the “cinema” folder
    • Create a folder labeled “templates”
    • Inside the “templates” folder create another folder and label it “cinema”
    • Inside the “cinema” folder you have just created inside the “templates” folder
    • Create the following blank HTML pages; index.html, base.html, confirm_delete.html, movie_bookings_detail.html, movie_bookings_list.html, movie_date_times_detail.html, movie_date_times_list.html, movie_dates_detail.html, movie_dates_list.html, movies_detail.html, movies_list.html and movies_image_details.html.

4. Below is a screenshot of the “cinema” directory tree:

5. Below are the HTML codes to be placed on each HTML page:

Creating the “Cinema” App URLs

These are the URLs that will be used by the user to navigate the “cinema” web app. They are usually placed in a file called “URLs.py”. Do the following to create/edit this file:

  1. Open the “cinema” app folder
  2. Locate/create a python file labeled “URLs.py”
  3. Paste the code below

Configure Project URLs

This is where the URLs that point to each Django app and A.P.I. are placed so that they are accessible from a browser. They are usually placed in a file called “URLs.py”. Do the following to create/edit this file:

  1. Open your Django project folder: “cinemabooking”
  2. Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “cinema” app folder
  3. Open the “cinemabooking” folder that is inside Django project folder
  4. Locate/create a python file labeled “URLs.py”
  5. Paste the code below

Project Tree

Below is a screenshot of how your project tree should look like, assuming the name of your Django project is “cinemabooking”:

Run the server

  1. cd/navigate into the “cinemabooking” Django project via the terminal
  2. Activate the virtual environment by typing the command: “venv\Scripts\activate”
  3. Start the server by typing the command: python manage.py runserver
  4. If there’s nothing wrong, the server should be up on http:127.0.0.1:8000

Testing the System

  1. Once the server is up
  2. Go to the web page address e.g. http://127.0.0.1:8000 or to the ngrok URL you had created
  3. Follow the instructions on the home page on how to test the system

NB: If you had quit or closed the ngrok terminal, after creating the URL, restarting the ngrok app terminal will lead to the creation of a new ngrok URL. You will need to update Africa’s Talking U.S.S.D. A.P.I. call back with this new URL and you will also need to update the python variable ALLOWED_HOSTS inside the settings.py file located inside the folder labeled “cinemabooking”

Conclusion

You should now have a basic understanding of how Africa’s Talking U.S.S.D. A.P.I. and S.M.S. shortcode works and how to implement them in python, while working in Django.

Further improvements could be done on the project such as, allowing clients to pay for the fees using Africa’s Talking Payment A.P.I.s.

Finally, you can find the code snippets in this @repo.

Quick Guide

If you just want to clone the project and get it up running, below is how to do so in minutes:

  1. Clone it:
    • git clone https://bitbucket.org/dans0l/cinemabooking.git
  2. Cd into it:
    • cd cinemabooking
  3. Create a venv:
    • python3 -m venv venv
  4. Activate venv:
    • Mac/Linux: source venv/bin/activate
    • Windows: venv\Scripts\activate
  5. Install the requirements:
    • pip install -r requirements.txt
  6. Create DB
    • python manage.py makemigrations
  7. Apply DB Changes:
    • python manage.py migrate
  8. Create a Ngrok URL:
    • Download the ngrok software from their website here: https://dashboard.ngrok.com/get-started/setup, on this page they you will be prompted to sign up to download the application, go ahead and do so.
    • Download and start/run the application
    • After running the Ngrok application you will see the ngrok terminal window
    • Go back to the Ngrok web page where you downloaded the application (the link is displayed above) and navigate to the section labeled “Connect your account”
    • Copy the ngrok code provided in the “Connect your account” section onto the Ngrok terminal
    • Inside the Ngrok terminal, type the command “ngrok http 8000”
    • A ngrok shell window will be displayed, with the name of the newly created ngrok http URL e.g. http://231fd19e6a93.ngrok.io
    • Do not close or quit this ngrok shell
  9. Generating Africa’s Talking A.P.I. Key:
    • Navigate to this URL https://account.africastalking.com/apps/sandbox/settings/key you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
    • While on this page enter your africa’s talking account password and click on the button labeled “Generate”
    • Your API key will be generated and displayed to you
    • Copy and paste it in a Notepad or somewhere you will remember
  10. Configure your Africa’s Talking SMS Short code:
    • Navigate to this URL: https://account.africastalking.com/apps/sandbox/sms/shortcodes: you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
    • While on that page click on the link labeled “create a short code” to create a USSD code
    • Enter a unique dummy short code e.g. 12435
    • Open the cloned project
    • Open the “api” folder
    • Open a python file labeled “send_message.py”
    • Enter the A.P.I. Key and your unique dummy short code credentials in the file
  11. Configure your Africa’s Talking U.S.S.D. A.P.I.:
    • Navigate to this URL: https://account.africastalking.com/apps/sandbox/ussd/codes you will be required to sign in or sing up if you don’t have an account with Africa’s Talking
    • While on that page click on the link labeled “create a channel” to create a USSD code
    • Enter a unique dummy channel e.g. 12345
    • Your U.S.S.D. Code is now e.g. *384*12345#
    • In the callback URL paste the ngrok http URL you created above, after appending “/api/ussd_callback/” at the end of the URL e.g. http://231fd19e6a93.ngrok.io/api/ussd_callback/ this “/api/ussd_callback/” A.P.I. has already been created in the Django project.
    • Click on Create Channel
  12. Configure the Django Project to use the created ngrok URL:
    • Open your Django project folder: “cinemabooking”
    • Locate a folder with a similar name to your Django project folder, this folder is in the same directory as your “cinema” app folder
    • Inside this folder is a python file labeled “settings.py”
    • Open the “settings.py” file and locate the python variable ALLOWED_HOSTS, which is a python list located close to the start of the file
    • Inside the ALLOWED_HOSTS list enter the ngrok URL you created as well as the localhost URL, it should resemble something like this: ALLOWED_HOSTS = [‘127.0.0.1′,’231fd19e6a93.ngrok.io’]
  13. Run the server:
    • python manage.py runserver
  14. Navigate to the site: http://127.0.0.1:8000
  15. Follow the instructions on the home page to start using the site

Please let me know how your experience was, Thank you.



0 Shares:
You May Also Like