Record

This element lets you record a call session into an mp3 file that you can then retrieve and play later. Our API supports partial recording or terminal recording. Partial recording is useful where a particular user response is required like while prompting for a name. For terminal recording, the recording starts when the record action is called until the mobile user hangs up.

Partial Recording

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

To read more about including prompts for inputs, see this

Here is a sample response:

<Response>
	<Record finishOnKey="#" maxLength="10" trimSilence="true" playBeep="true">
		<Say>Please tell us your name after the beep.</Say>
	</Record>
</Response>

When the recording ends, 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. The call proceeds based on the response to that notification.

Attribute Description
finishOnKey
Optional
This shows the number of digits you would like to grab from the user input. Default: None
maxLength
Optional
This specifies the maximum amount of time in seconds a recording should take. Default: None
timeout
Optional
This specifies timeout in seconds. Default: 3600
trimSilence
Optional
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. Default: false
playBeep
Optional
This is a boolean attribute which specifies whether the API should play a beep when the recording starts. Default: false
callbackUrl
Optional
This is the URL of the script to process the recording mp3 file sent by the API. If absent, our API will forward the request to the default URL for this phone number. Default: None

Terminal Recording

Terminal recording doesn't have any attributes. No other action will be executed after.

<Response>
	<Say playBeep="true">Please leave a message after the beep.</Say>
	<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
// 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'];
}

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.

<?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

}