Get Digits

You can use this action 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.

To read more about including prompts for inputs, see this

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, if a GetDigits action receives no input at all, it will move on to the next action without triggering a notification. This means that if it is the last action the call will be terminated if the user does not include any input. If you would like us to say something before hanging up, you can 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>

The GetDigits action can take these attributes:

Attribute Description
numDigits
Optional
This shows the number of digits you would like to grab from the user input. Default: None
timeout
Optional
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. Default: 30 Seconds
finishOnKey
Optional
The key which will terminate the action of getting digits. Default: None
callbackUrl
Optional
The 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 issued). Default: None

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

}