Record

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

This element lets you record a call session into an mp3 file that you can then retrieve and play later.

Our API support terminal recording or partial recording.

For final recording, the recording starts when the record action is called until the mobile user hangs up.

Partial recording may be useful where a particular user response is required like while prompting for a name


Partial recording sample implementation

Attribute Description Required Default
finishOnKey Optional attribute which tells the API where the recording should stop. You may inform the user to press 1 when done talking to mark the end of the recordable part. No N/A
maxLength Optional attribute which specifies the maximum amount of time in seconds a recording should take. No N/A
timeout Optional attribute which specifies timeout in seconds. No 3600
trimSilence This is a boolean attribute which specifies whether you want to remove the initial and final parts of a recording where the user was silent. No false
playBeep This is a boolean attribute which specifies whether the API should play a beep when recording starts. No false
callbackUrl Optional attribute containing the URL of the script to process recording mp3 file sent by the API. If not set, the recording is sent to your current callbackUrl (The script which with the XML response).
When callbackUrl is used, the callbackUrl to handle any call request for the current call changes to the callbackUrl set.
No Current callbackUrl

A recording stops when finishOnKey button is pressed, timeout or maxLength time is reached or the user hangs up.

Here is a sample response :

The URL of the recorded file will be sent in the final response from our APIs in a field named recordingUrl. If no file was recorded, this variable will contain an empty string.

Sample PHP Implementation

Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to voicemail.php. Below is an example of how you can implement a simple voicemail system by combining the Say and Record elements.
<Response>
	<Record finishOnKey="#" maxLength="10" trimSilence="true" playBeep="true">
		<Say>Please tell us your name after the beep</Say>
	</Record>
</Response>

You can use Play or Say within the record attribute

The URL of the recorded file will be sent to the same callbackUrl which requested the recording in a POST parameter recordingUrl. If no file was recorded, this variable will contain an empty string.

Sample PHP Implementation

Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to voicemail.php. Below is an example of how you can implement a simple voicemail system by combining the Say and Record elements.

You will need to add some functions to persist the call session (saveCurrentCallState, getCallState).

They may persist it in any DB (MYSQL, Redis server, etc) or in files.

We will assume we have 3 states. None(represented by an empty string), PromptName, PromptLocation

<?php
// First read a couple of the 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)  {
	
	// Get the current state of the call. You may use a database or file to store call session data but we have use PHP sessions
	
	$currentState = getCallState($sessionId);
	
	if($currentState == "") {
			//This is the first time the callback has been accessed and we want to prompt the user 
		
			// Compose the response  
			$response  = '<?xml version="1.0" encoding="UTF-8"?>';
			$response .= '<Response>';
			$response .= '<Record finishOnKey="#" maxLength="10" trimSilence="true" playBeep="true"/>';
			$response .= '<Say>Please say your name after the beep.</Say>';
			$response .= '</Record>';
			$response .= '</Response>';
			
			// set currentState to PromptName
			saveCurrentCallState($sessionId, "PromptName");
	}
	
	elseif($currentState == "PromptName") {
		  $recordedName = $_POST['recordingUrl'];
			
			//Persist the recordedName in your storage. Its an MP3 file
			
			//Thank the user for leaving their name
			$response  = '<?xml version="1.0" encoding="UTF-8"?>';
			$response .= '<Response>';
			$response .= '<Record finishOnKey="#" maxLength="10" trimSilence="true" playBeep="true"/>';
			$response .= '<Say>Please say your location after the beep.</Say>';
			$response .= '</Record>';
			$response .= '</Response>';
			
			saveCurrentCallState($sessionId, "PromptLocation");
	}
	
	
	elseif($currentState == "PromptLocation") {
		  $recordedLocation = $_POST['recordingUrl'];
			
			//Persist the recordedLocation in your storage. Its an MP3 file
			
			//Thank the user for leaving their name
			$response  = '<?xml version="1.0" encoding="UTF-8"?>';
			$response .= '<Response>';
			$response .= '<Say>Thank you for the information. Our pizza delivery guy is on the way.</Say>';
			$response .= '</Response>';
	}
					 
				// Print the response onto the page so that our gateway can read it
	header('Content-type: application/xml');
	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'];
}

Terminal recording sample implementation

Final recording doesn't have attributes.
It is a terminal action. ie. No other action will be executed after.

Here is a sample response :

<Response>
<Record/>
</Response>

The URL of the recorded file will be sent in the final response from our APIs in a field named recordingUrl. If no file was recorded, this variable will contain an empty string.

Sample PHP Implementation

Assuming that you have configured the callback URL for your Africa's Talking Phone Number to point to voicemail.php. Below is an example of how you can implement a simple voicemail system by combining the Say and Record elements.
<?php
// Save this code in voicemail.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/voicemail.php

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

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

// The caller number
$callerPhoneNumber = $_POST['callerNumber'];

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

if ($isActive == 1)  {

// Inform the caller that while you may not be available at the moment,
// you will be happy to take a message

// Compose the response  
$response  = '<?xml version="1.0" encoding="UTF-8"?>';
$response .= '<Response>';
$response .= '<Say playBeep="true">Please leave a message after the tone.</Say>';
$response .= '<Record/>';
$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'];

// Be sure to read in the URL of the recorded conversation
$recording    = $_POST['recordingUrl'];

// You can then store this information in the database for your records

}