Programmer Level

1. Beginner

SMS

Send SMS

In order to send an SMS, you have to require the africastalking module; then set your name and api_key on an options object that will be passed on to the module's constructor.

We then copy the SMS module from the africastalking module; and invoke its send method with an opts variable which includes the message we want to send. Here is a sample.

var options = { apiKey: 'YOUR_API_KEY', username: 'YOUR_USERNAME', format: 'json' // or xml};

var AfricasTalking = require('africastalking')(options);

var sms = AfricasTalking.SMS;sms.send(opts) .then(

function(s) { console.log(s); }) .catch(function (error) {

console.log(error);

}

);

AIRTIME

Sending airtime

Require africastalking module

npm install --save africastalking
set up your API username and api_key on an options variable
require the airtime module
send airtime

var options = { apiKey: 'YOUR_API_KEY', username: 'YOUR_USERNAME', format: 'json' // or xml};

var AfricasTalking = require('africastalking')(options.AT);

var airtime = AfricasTalking.AIRTIME;

var opts = { 'recipients': [{ "phoneNumber": '+254701435178', "amount": '10' }] };

airtime.send(opts) .then(function(s) { console.log(s); }) .catch(function (error) { console.log(error); });

In this example; we store the recipients as a JSON object, it contains a key with a value of type list. This allows you to send different amounts to different numbers. The call to send airtime is promise based, this means we have to define a then object on the call to handle a successful call to send airtime, and a catch so we can throw or report any errors that might occur.

Airtime delivery reports

Now that we have sent airtime; how do we check if the airtime was delivered to the recipient? We invoke delivery reports whenever you send airtime, we allow you to add a callback that we invoke when we receive a delivery report. In this example we use express.

'use strict';

exports.airtimeDLR = function(req, res) {

var status = req.body.status;

var requestId = req.body.requestId;

console.log(messageId, status);

res.send(200); // return 200

};

We return a 200 to notify the API that we have received the message. In this example we just log the delivery event. You should also persist this to DB.

VOICE

Making a voice call

In this section we require node, and this environment setup configured; check link <here>.

With voice; before making a call, you need a virtual number mapped to your account. You can raise one on the sandbox here. We copy the voice module from the africastalking module we have just imported, you then invoke the call method on the voice module. In order to make a call, you have to pass a JSON object to the call method with the virtual number you’re calling from and the number you’re calling.

To throwany errors; we have to catch the call and handle the error appropriately by reporting or just logging for debugging purposes.

var AfricasTalking = require('africastalking')(options.AT);

var voice = AfricasTalking.VOICE;

var options = { apiKey: 'YOUR_API_KEY', username: 'YOUR_USERNAME', format: 'json' // or xml};

voice.call({ callFrom: '+254711082XXX', callTo: '+254701XXXXXX' })

.then(function(s) { console.log(s); }) .catch(function(error) { console.log(error); });

Handling a voice call

Now that we’ve made a call from a virtual number; how do we handle the call? What if the

virtual number is called? What happens?

For any call handled, whether made to the virtual number or from the virtual number the API gateway will invoke your voice callback, you need to specify a callback for this to work. You can add one <here>.

When we handle a call mapped to your number, we invoke your callback_url; we send POST params to your API; you must handle a POST request on your callback_url.

var options = { apiKey: 'YOUR_API_KEY', username: 'YOUR_USERNAME', format: 'json' // or xml};

exports.voice = function(req, res) {

console.log(req.body);

var response = "<Response><Say> Hey, thank you for testing </Say></Response>";

res.setHeader('Content-Type', 'text/plain');

res.send( response);

};

We have an options object; this is used as a store for your credentials, so make sure to update and add your username and api_key. We create a response by generating an XML string; voice works with commands that you send by returning an XML string as a response. This XML string must contain a valid XML response command. A list of valid commands and validations exist <here>. We log the request body, the API sends the these parameters.

You have to set a header of text/plain and return a valid XML response. While debugging check the voice application on the sandbox you can check the logs <here>; this will help you catch any errors in the XML response that was generated.

USSD

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

exports.sampleUSSD = function(req, res) {

var message = '';

var sessionId = req.body.sessionId;

var serviceCode = req.body.serviceCode;

var phoneNumber = req.body.phoneNumber;

var text = req.body.text;

var length = text.split('').length;

var txt = text.split('');

if (text === '') {

message = 'CON Welcome to Sample USSD Code LTD\n';

message += '1: Enter new device \n';

message += '2: Enter sales person\n';

} // add device

else if (text === '1') {

message = 'CON Enter device IMEI number';

} else if (length === 2 && txt[0] === '1') {

message = 'CON Enter device color';

} else if (length === 3 && txt[0] === '1') {

message = 'CON Enter device model\n';

message += 'eg. Nokia 3310';

}else if (text === '2') {

message = 'CON Enter sales agent name\n';

} else if (length === 2 && txt[0] === '2') {

message = 'CON Enter sales agent email';

} else {

message = 'END Wrong input'; // reply with menu

}

res.contentType('text/plain');

res.send(message, 200);

};

In this sample, we respond with a menu and ask the user for input, and interact with them further by asking them to enter information about the device and agents depending on the menu option they entered.

Programmer Level