Get Started

Twilio Client Audio Recording

Twilio Client provides an easy way for your website visitors to create audio recordings using a usb headset or microphone. Twilio Client can make use of any TwiML tag, such as Record, making it easy to bring custom call flows to the browser.

Usage

A website user views a web page with a button labelled 'Start Recording' and a status field reading 'Ready to start recording'. Upon clicking the button the status label will read 'On Air' and the user will hear instructions to leave a message after the beep. The recording will begin and the user can talk until they click a 'Stop Recording' button, or the recording will time out after 30 seconds. After the recording is complete, the message will be played back for the user to hear. The recording will then be available for future use via the Twilio REST API.

Concepts

This HowTo demonstrates browser audio recording using Twilio Client, specifying an outgoing connection to a Twilio Application, and creating TwiML call logic using the <Say>, <Record> and <Play> verbs.

Download

browser-record.zip

Implementation

  1. Generate a Twilio Capability Token with outgoing permissions
  2. Create javascript to set up a Twilio.Device and HTML to initiate a connection
  3. Web user clicks a button to initiate an outgoing connection, and Twilio requests the Voice Url of the Application specified in the TwilioCapability
  4. The Application responds with TwiML instructions to record a message.
  5. Twilio establishes a connection to the browser and executes the call flow. The recording is taken and will be saved into the Twilio account.

Get Started

  • 1

    • howtos/browser-record/browser-record.php
      include 'Services/Twilio/Capability.php';
      $accountSid = 'ACxxxxxxxxxx';
      $authToken  = 'xxxxxxxxxxxx';
      $token = new Services_Twilio_Capability($accountSid, $authToken);
          
  • 2

  • Create HTML and Javascript for the 'Begin Recording' and 'Stop Recording' buttons and a div to hold status information. Set the initial visibility of the 'Stop Recording' button to 'none'.

  • howtos/browser-record/browser-record.php
    			<h3>Create a Recording</h3>
    			<input type="button" id="call" value="Begin Recording"/>
    			<input type="button" id="hangup" value="Stop Recording" style="display:none;"/>
    			<div id="status">
    				Offline
    			</div>
        

Add javascript to setup a Twilio.Device with the capability token. We use jQuery to create click handlers for the 'Begin Recording' and 'Stop Recording' buttons as well as register Twilio.Device callback functions to update the status text. We also toggle the visibility of the buttons when a call is in progress.

  • howtos/browser-record/browser-record.php
    		<script type="text/javascript" src="//static.twilio.com/libs/twiliojs/1.1/twilio.min.js"></script>
    		<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.6.1/jquery.min.js"></script>
    		<script type="text/javascript">
    		var connection=null;
    		$(document).ready(function(){
    			Twilio.Device.setup("<?php echo $token->generateToken();?>",{"debug":true});
    			$("#call").click(function() {  
    				Twilio.Device.connect();
    			});
    			$("#hangup").click(function() {  
      				connection.sendDigits("#");
    			});
    
    			Twilio.Device.ready(function (device) {
    				$('#status').text('Ready to start recording');
    			});
    
    			Twilio.Device.offline(function (device) {
    				$('#status').text('Offline');
    			});
    
    			Twilio.Device.error(function (error) {
    				$('#status').text(error);
    			});
    
    			Twilio.Device.connect(function (conn) {
    				connection=conn;
    				$('#status').text("On Air");
    				$('#status').css('color', 'red');
    				toggleCallStatus();
    			});
    
    			Twilio.Device.disconnect(function (conn) {
    				$('#status').html('Recording ended<br/><a href="show_recordings.php">view recording list</a>');
    				$('#status').css('color', 'black');
    				toggleCallStatus();
    			});
    			
    			function toggleCallStatus(){
    				$('#call').toggle();
    				$('#hangup').toggle();
    			}
    		});
    		</script>
        
  • 3

    • User clicks the 'Begin Recording' button which invokes Twilio.Device's connect method. Twilio requests the Voice Url specified in the Application for instructions on how to handle the call logic.
  • 4

    • The Voice URL specified in the Application will respond to Twilio's request with TwiML.

    • The TwiML uses the <Say> verb to speak a greeting then uses <Record> to begin audio recording. If a recording is detected the TwiML flow will submit to the URL specified in the <Record> 'action' attribute, otherwise the call flow will continue on to <Say> a recording was not detected and hangup the call. For a complete overview of TwiML (Twilio's XML) see the TwiML documentation.

  • howtos/browser-record/browser-record-twiml.xml
    <?xml version="1.0" encoding="UTF-8"?>
    <Response>
        <Say>
            Please record your message at the beep. 
        </Say>
        <Record
            action="recording-goodbye.php"
            method="GET"
    		finishOnKey="#"
            maxLength="30"
            />
        <Say>I did not hear a recording.  Goodbye.</Say>
    </Response>    
  • 5

    • The <Record> tag submits to it's action url and Twilio will pass the RecordingUrl parameter. The recording is played back and the call is completed.
  • howtos/browser-record/recording-goodbye.php
    <?php  
    header("Content-type: text/xml");
    echo "<?xml version='1.0' encoding='ISO-8859-1'?>";
    ?>
    <Response>
    	<Say>Thanks for your recording.  Here is what I heard</Say>
    	<Play><?php echo $_REQUEST['RecordingUrl']; ?></Play>
    	<Say>Goodbye</Say>
    </Response>    

The list of account recordings may be accessed using the REST API.

  • howtos/browser-record/show_recordings.php
        // Instantiate a new Twilio Rest Client 
    	$client = new Services_Twilio($accountSid, $authToken);
    	echo ("<table>");
    	foreach($client->account->recordings as $recording) {
      		echo "<tr><td>{$recording->duration} seconds</td> ";
      		echo "<td><audio src=\"https://api.twilio.com/2010-04-01/Accounts/$accountSid/Recordings/{$recording->sid}.mp3\" controls preload=\"auto\" autobuffer></audio></td>";
      		echo "<td>{$recording->date_created}</td>";
      		echo "<td>{$recording->sid}</td></tr>";
    	}
    	echo ("<table>");