In this walk through we shall be building a platform to enable a hypothetical company have their agents call ‘leads’ without the leads actually knowing the agents number. This concept of hiding the number from one party is called number masking.
An excerpt from the Africa’s talking website:
With simplified access to telco infrastructure, developers use our powerful SMS, USSD, Voice, Airtime and Payments APIs to bring their ideas to life, as they build and sustain scalable businesses.
- Basic knowledge of Java and Spring boot
- Basic knowledge of android using Java
- An Africa’s Talking account with a test number [get clarification on how to navigate a brand new user to the register page now that the sandbox isn’t working]
- A working phone number with atleast 5/- airtime
- Ngrok – This tutorial uses the free version of Ngrok to expose the apis. You could use a domain you own for this but that is not in scope
How it will work
In this and the next article, we will be using a sales team in a hypothetical company that uses an android app to store and access customer lead information. This lead information is then stored on a database using spring boot and a H2 database. Anyone in the sales team can call any of the leads but on the side of the ‘lead’ they will always see one number – the number that is registered on the Africa’s Talking (AT) platform. This way the people in the sales team keep their numbers private while effectively closing leads. When the sales team people initiate the call (through the app) the api and saved data will give them context so that they don’t go into the call blind. From the side of the customer, they can always call back the company number and their number will be logged into the system to automatically request a callback.
We have to register a callback and events url (that we create and expose using Spring boot + Ngrok) on the Africa’s talking dashboard to connect this number to our code.
A quick note:
The 10/- credit allocated in your AT account is sufficient for this tutorial but should it get depleted before you are done, there are ways to load up more airtime on the platform [get clarification here].
Let us begin with the spring boot side of things.
Go to spring initializr and fill in the fields and dependencies as shown in the screenshot below:
You can change the group name to match your name. Download the zip file, extract it and open in with your IDE of choice.
The first thing we will do is folder management. Create packages for the following, models, controllers and repositories. We will handle two types of entities here, the agent data and the customer data. Customer data will be mapped to an agent because leads are usually not shared.
Before we start, let us enter the following in the application.properties. We will be using the h2 database to persist data to a file.
We shall do the customer modelling first without the africa’s talking api in 2 parts:
- Data, apis and logic for the agent
- Data, apis and logic for the customer and do the data mapping plus update the apis
Let us create our first data model – Agent Model
Create a data repository – AgentRepository.java which we will use to manipulate data in the database. We have a method here to search an agent by phone number.
To make the api calls and actually manipulate the data, we create an agent controller. Here we save the agent from the api call and we do a check to see whether the agent exists or not using the phone number.
We then create the customer model.
We create a customer dto, a customer data repository and a customer controller to manipulate the customer data. All files below:
At this point, we can save an agent, save and update the customer (lead) and successfully retrieve leads per customer. Now for the AT voice api. If you don’t have a test number yet, please refer to the first section of this article and get it as it is impossible to move forward without it.
We add the repository and dependency for the SDK as stated in this link and sync the spring boot project. Every call that is made to the test number provided by AT will hit this api and run whatever command you want for it. You have to register your callback and event urls in the dashboard, under your test number, under the callback option.
Since I don’t have a domain to work with for now, I use Ngrok to create a tunnel from my spring boot code to the internet. Let us make a simple controller to test everything out.
First create a voice response model.
This is the data that the api will always send to our callback when a call is made to the number.
The logic for the voice controller will be as follows:
- If an agent is calling, we look at the leads (customers) then check the one with the flag calling to be true – this flag will be set from the mobile app in the next tutorial. Once we know who the agent is calling, we create a say method, give the agent the customers name and proceed to call the customer. Once the call is done, we then update that record to have calling == false and contacted == true. If by any chance there is no flag for true, we then end the call for the agent immediately after playing them an automated error message
- If a customer is calling, we play them a message saying that they will be called back then we end the call. Before ending the call, we check whether the customer was in the system or not. If they were in the system, we update their record to contacted false and set a message of “requested callback”
Here is the complete Voice Controller code:
If you mapped ngrok or your domain correctly, run the spring boot project and call the test number that was provided. You should hear the voice with this text “Thank you for calling. We shall call you back as soon as possible. Goodbye”, a beep then the call will end. You can tweak the voice and hear the two kinds that are available from the api.
Please note that your number (not the AT number) will be charged for this call. At this point, the number you used to call the AT number has been saved as a ‘prospect’ in the database – customer table.
With that we are done with the spring boot side of things. Now to move to android to create an app that consumes this api and handles all the logic.
For simplicity, this android app will have 3 parts. The agent sign up screen, the leads list screen and the leads info screen. Let us begin:
Create an android project based on the Basic Activity screen. Give it appropriate properties. Follow the screens below:
We need to install Retrofit using the code below.
Now that retrofit is installed, we need to create the api interface and builder classes.
This api references the agent and customer models. Let us create them.
We also create a CustomerDto model to be used with the fragments/activity.
We need an adapter to display the results from the leads list api call.
We start with the splash screen. This is the first screen an agent will have access to and if they had not registered with the api before, it means the entry in sharedPreferences will be null, so they will be directed to the AgentSignupActivity.java file.
Next, we move to the main activity which holds both fragments for the lead listing and list calling/addition.
Next we have the main fragment that holds all the logic for listing and displaying all the leads.
Lastly we have the leadinfo fragment that holds logic for adding a new lead to the system and calling a selected lead by making the api call to change the status first, then using an intent to call the AT number provided.
To tie up everything together, here is the manifest file with the permissions needed.
Working with the apis from Africa’s talking is straight forward and this example shows how easy is it to integrate the voice api to a workflow.
The git repo for the android section can be found here.
The git repo for the spring section can be found here.
Documentation for the voice api can be found here.