Handling a call

Handling calls made to your Africa's Talking phone number is as easy as implementing a script on your web server that handles POST requests.

Jump To:

Steps Involved In Handling A Call Session [Go Top]

Here is how it all comes together...

1. We receive a call to your phone number on our voice gateways, or you successfully initiate a call using our calling API

2. Our API sends a POST request to the URL that you have set for that phone number in your Voice Dashboard.

3. Your application responds with XML that tells our API how to handle the call. This XML will typically contain a list of actions that our API will execute in sequence.

4. Our API translates those actions into events or messages relayed back to the caller

POST Variables Sent From Our APIs [Go Top]

The post request that we submit to your callback URL will contain the following variables:
Variable Name Description Presence
isActive This variable lets your application know whether the call is in session state. The API will set a value of 0 in the final request to your application. That request will contain details about the call's duration and cost. All requests
sessionId This is a unique identifier that we will generate during each call session. This variable will stay the same throughout the call All requests
direction Whether this is an inbound or outbound call. Inbound calls are initiated by a phone user while outbound calls are initiated by your application. All requests
callerNumber The phone number of the phone user in the call. The phone numbers are all in international format, starting with a + (such as +254711XXXYYY) All requests
destinationNumber Your Africa's Talking phone number. This will also be presented in international format, starting with a +. All requests
dtmfDigits This variable contains the digits that a user enters in response to a getDigits request Request following a GetDigits response
recordingUrl The URL of the recording made for this call (using either the Record element, or the record attribute of the Bridge element Final Request
durationInSeconds The duration of the call in seconds. Final request
currencyCode The currency used to bill this call (e.g KES, USD, GBP). Final request
amount The total cost of the call. Final request

So...what does a voice application actually look like? [Go Top]

Well, it now looks just like your regular web application. Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to checkBalance.php. Below is an example of how you would use PHP to handle an incoming call, check the user's balance and respond by reading him the result:
// Save this code in checkBalance.php. Configure the callback URL for your phone number
// to point to the location of this script on the web
// e.g http://www.myawesomesite.com/checkBalance.php

// First read in a couple of POST variables passed in with the request

// This is a unique ID generated for this call
$sessionId = $_POST['sessionId'];

// Check to see whether this call is active
$isActive  = $_POST['isActive'];

if ($isActive == 1)  {
  // Read in the caller's number. The format will contain the + in the beginning
  $callerNumber = $_POST['callerNumber'];

  // You can replace this array with an actual database table
  $balanceArr = array(
		     '+254711XXXYYY' => 100,
		     '+254733YYYZZZ' => 150,
		     '+254711000ZZZ' => 190,
  // Read the caller's information from the database if necessary
  if ( array_key_exists($callerNumber, $balanceArr) ) {
    $balance = $balanceArr[$callerNumber];
    $text    = "Your balance is " . $balance . " shillings. Good bye.";
  } else {
    $text = "Sorry, your phone number is not registered for this service. Good Bye.";
  // Compose the response
  $response  = '<?xml version="1.0" encoding="UTF-8"?>';
  $response .= '<Response>';
  $response .= '<Say>'.$text.'</Say>';
  $response .= '</Response>';
  // Print the response onto the page so that our gateway can read it
  header('Content-type: text/plain');
  echo $response;

} else {
  // Read in call details (duration, cost). This flag is set once the call is completed.
  // Note that the gateway does not expect a response in thie case
  $duration     = $_POST['durationInSeconds'];
  $currencyCode = $_POST['currencyCode'];
  $amount       = $_POST['amount'];
  // You can then store this information in the database for your records