Programmer Level

1. Beginner

To get started Install maven/sbt/ gradle so as to install dependencies.

SMS

Sending an SMS

To send an SMS make sure you have installed AfricastalkingGateway library. Create a class and a main instance to provide an entry point so as to invoke sendMessage action. Specify your username and api_key; if you don’t know your api_key create one from <here>. Specify a recipient, message to send and create an instance of the gateway class passing your username and api_key to authenticate to the API.

/ Make sure the downloaded jar file is in the classpath or has been added to referenced libraries if you are using an SDK like eclipse or netbeans/import java.util.HashMap;

import com.africastalking.AfricasTalkingGateway;public class TestSMSSending { public static void main(String[] args) { // Specify your login credentials String username = "username"; String apiKey = "APIKey"; AfricasTalkingGateway gateway = new AfricasTalkingGateway(username, apiKey);

// Specify the numbers that you want to send to in a comma-separated list // Please ensure you include the country code (+254 for Kenya in this case) // Create a new instance of our awesome gateway class

gateway.sendMessage("254711XXXYYY","hello");}

AIRTIME

Sending airtime

In this example send airtime example; we look at using java to send airtime to recipients; we’ll top up different numbers with different amounts. For this example, we require the org.json library to marshall and unmarshall JSON objects.

import org.json.*;

import com.africastalking.AfricasTalkingGateway;public class TestSendAirtime { public static void main(String[] args) { String username = "myAfricasTalkingUsername"; String apiKey = "myAfricasTalkingAPIKey"; JSONArray recipients = new JSONArray(); // Add the first recipient and the amount as a json object to the json array

// Specify phone number in international format recipients.put(new JSONObject()

.put("phoneNumber","+254711XXXYYY")

.put("amount","KES XX"));

String recipientStringFormat = recipients.toString(); //Create an instance of our awesome gateway class and pass your credentials AfricasTalkingGateway gateway = new AfricasTalkingGateway(username, apiKey);

gateway.sendAirtime(recipientStringFormat);

}}

VOICE

Making a voice call

To successfully initiate a call you need a virtual phone number, you can create one from <link> on the sandbox. This is the number that will initiate the calls, it must be in international format. Create a class and define a main method; this will be your entry point to the gateway’s call method. You have to create a gateway instance and initialize it with your AT username and api_key.

import org.json.;import com.org.AfricasTalkingGateway.;public class TestMakeCall { public static void main(String[] args) { // Specify your login credentials String username = "MyAfricasTalking_Username"; String apiKey = "MyAfricasTalking_APIKey"; // Specify your Africa's Talking virtual phone number in international format String from = "+254711082XXX"; // Specify the numbers that you want to call to in a comma-separated list // Please ensure you include the country code (+254 for Kenya in this case) String to = "+254711XXXYYY"; // Create a new instance of our awesome gateway class AfricasTalkingGateway gateway = new AfricasTalkingGateway(username, apiKey); // Any gateway errors will be captured by our custom Exception class below, gateway.call(from, to); }}

Handling a voice call

To handle a call, you need to handle a POST request to a route that you have saved as a callback <here> In this sample we use Spark, a simple micro-framework. You have to set up a POST handler with Spark, here’s a sample.

package com.africastalking.app.routes;import static spark.Spark.post;public class VoiceRouter extends BareBonesRouter { public String message; public void voiceRouterCall(String mesg) { message = mesg; } @Override protected void doPost() { post("/voice/", (req, res) -> { String status = req.queryParams(":isActive"); if (status.equals("1")) { res.body(

"<?xml version='1.0' encoding='UTF-8'?>" \

"<Response><Say>'Hello, thank you for calling'</Say></Response>"

); } res.status(200); return res; }); }}

We define a POST handler function, called doPost, you then have toadd this to the base router object so the url can be active; you initially create a router that extends the BareBonesRouter and override thedoPost method to enable the class to handle POST requests.

USSD

Posting a USSD menu

Handling USSD calls is through a callback, so you must set a callback url and own a USSD code, you can raise one <here> on the sandbox. Whenever the USSD code is dialled, we POST parameters to your callback url; you then return a response string, that must start with a CON/ END. CON allows you to continue processing other USSD requests and will display an input when dialled while END is terminal and terminates the USSD session. Some for the POST parameters we send are:

  • serviceCode
  • sessionId
  • phoneNumber
  • Text

We can use Spark to set a POST handler to process POST requests and return string responses for USSD.

@Overrideprotected void doPost() { post("/ussd/", (req, res) -> { String sessionId = req.params("sessionId"); String phoneNumber = req.params("phoneNumber"); String text = req.params("text"); String response, message = "The best things in life are free";

switch (text) { case "": response = "CON What service would you like \n" + "1. A voice call from Africa`s Talking\n" + "2. SMS from Africa's Talking "; break; case "1": response = "END Thank you, You will receive a phone call\n"; new Call().call(message, phoneNumber); break; case "2": response = "END Thank you, You will receive an SMS"; new Message().sms(message, phoneNumber); break; default: response = "END Invalid input"; }

res.body(response); return response; });

In this example, we generate a USSD menu with two options that lead to an action over SMS, or voice. When the first option is selected; an SMS is sent to the dialler and when the second option is entered, the user is called. This project requires a full deployment using ngrok and a package manager to fetch the dependencies listed above; using maven or gradle. Check to install dependencies.

Adding gradle dependency

repositories { jcenter() maven { url "https://jitpack.io&quot; }}dependencies { compile 'com.github.AfricasTalkingLtd:africastalking-java:v1.0.0'}

Adding sbt dependency

resolvers += "jitpack" at "https://jitpack.io"libraryDependencies += "com.github.AfricasTalkingLtd" % "africastalking-java" % "v1.0.0"

Adding a maven dependency

Add this section to your pom.xml

<repositories> <repository> <id>jitpack.io</id> <url>https://jitpack.io</url&gt; </repository> </repositories>

<dependency> <groupId>com.github.AfricasTalkingLtd</groupId> <artifactId>africastalking-java</artifactId> <version>v1.0.0</version> </dependency>

2. Intermediate project

In this project; we use Spark to build a Java application that works with USSD, SMS, voice and Payments; you can download the project from <here>

Fetch dependencies: sbt run, or maven, or gradle build.

To compile:

  • Using sbt - compile
  • Using maven
  • Using gradle - gradle build

Install jdk version 6 and above.

Install Spark by following the build instructions above; this will compile and fetch all dependencies.

The application is written using the MVC pattern; this app consists of routes, models that interact with the database, a main app instance and utilities with a configuration file.

We use App.java as the main entrypoint; here we import all the routes and models and bind them to urls; the routers located in the routes folder, all extend from the baseRouter and allow us to define POST, GET route handlers for different classes.

The USSD router is different from the SMS router since it only handles POST requests; a class that extends a base router must extend all of its methods; allowing every method to be handled.

We also use a thread pool to handle requests, this allows us to not block and handle async requests concurrently but give us some level of safety when blocking occurs.

package com.africastalking.sample-app;

…

import static spark.Spark.*;public class App { public static void main(String[] args) { int maxThreads = 99; int minThreads = 9; port(8000); int timeOutMillis = 30000; threadPool(maxThreads, minThreads, timeOutMillis); before((request, response) -> { System.out.println(request); }); (new USSDRouter()).initiate(); (new MessagingRouter()).initiate(); (new VoiceRouter()).initiate(); }}

results matching ""

    No results matching ""