Get Digits

Have you registered a callback URL to receive requests for your virtual number? Please click here.

You can use this element to get the digits that a user enters on their phone in response to a prompt from your application. For example, you can ask the user to enter their account number, followed by the hash sign, and then read back their balance to them.

Here is a sample response, with a Say prompt:

<Response>
  <GetDigits timeout="30" finishOnKey="#">
    <Say>Please enter your account number followed by the hash sign</Say>
  </GetDigits>
</Response>

Once we get this response, our server will read out the text contained in the Say request to the caller and wait for the configured timeout for the response.

If the user successfully completed the request and presses the hash sign, our API will forward this response to your web server and fetch the next set of instructions. Otherwise, we will hang up. If you would like us to say something before hanging up, you can always add another element after the GetDigits request like this:

<Response>
  <GetDigits timeout="30" finishOnKey="#">
    <Say>Please enter your account number followed by the hash sign</Say>
  </GetDigits>
  <Say>We did not get your account number. Good bye</Say>
</Response>

Attributes

The GetDigits element can take these attributes:
Attribute Description Required Default Value
numDigits This shows the number of digits you would like to grab from the user input No None
timeout Timeout (in seconds) for getting the digits, after which the system moves on to the next element. If there is no other element to execute, the system will hang up No 30 Seconds
finishOnKey The (optional) key which will terminate the action of getting digits. If it is not specified, the API will send back the first digit that the user presses. No None
callbackUrl The (optional) parameter instructs us to forward the results of the GetDigits action to the URL value passed in. If absent, our API will forward the request to the default URL for this phone number (or to the redirected URL if a redirect has been issues).
This redirection is permanent.
No None

Child Elements

You can next either a Say element or Play element inside a GetDigits element. The child element is required, and will be used to prompt the user to enter digits into their phone.

Response

Once the user presses the digits successfully, our API will invoke your callback URL with the results being submitted using a variable named dtmfDigits. The example below shows a handler script that reads these values into an account number.

Sample PHP Implementation

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 handle an incoming call, check the user's balance based on their account number and respond with the result:
<?php
// 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'];

// For this example, we will assume that you persist the call state in 
// a database table, or in the current session. This function will
// retrieve that. For this example, the state goes from:
// None => PromptSent => Done
$currentCallState = getCallState($sessionId); // Implement this locally!

if ($isActive == 1)  {
  // The call is active
  
  if ($currentCallState == 'None') {
    
    // This is the First request we are receiving. Prompt for the account number
    // Compose the response
    $response  = '<?xml version="1.0" encoding="UTF-8"?>';
    $response .= '<Response>';
    $response .= '<GetDigits finishOnKey="#">';
    $response .= '<Say>Please enter your account number followed by the hash sign</Say>';
    $response .= '</GetDigits>';
    $response .= '</Response>';
    
    // Be sure to change the call state
    $currentCallState = 'PromptSent'
    
  } else if ($currentCallState == 'PromptSent' ){
    
    // This is the second request from Africa's Talking
    
    // You can replace this array with an actual database table
    $balanceArr = array(
			'1234' => 100,
			'1235' => 150,
			'1236' => 190,
			);

    // Read the dtmf digits
    $accountNumber = $_POST['dtmfDigits'];
    
    // Read the account information from the database if necessary
    if ( array_key_exists($accountNumber, $balanceArr) ) {
      $balance = $balanceArr[$accountNumber];
      $text    = "Your balance is " . $balance . " shillings. Good bye.";
    } else {
      $text = "Sorry, we could not find that account number. Good bye";
    }
    
    // Compose the response
    $response  = '<?xml version="1.0" encoding="UTF-8"?>';
    $response .= '<Response>';
    $response .= '<Say>'.$text.'</Say>';
    $response .= '</Response>';
    
    // Be sure to change the call state
    $currentCallState = 'Done'
    
  }
  
  // Ensure you save the call state. This could be a database call or a write to 
  // session storage
  saveCurrentCallState($sessionId, $currentCallState); // Implement this locally!
  
  // 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
  
  $callerNumber = $_POST['callerNumber'];
  $duration     = $_POST['durationInSeconds'];
  $currencyCode = $_POST['currencyCode'];
  $amount       = $_POST['amount'];
  
  // You can then store this information in the database for your records

}