Get Started

Voicemail Transcription

The Voicemail Transcription demo shows how to use Twilio's speech-to-text transcription API to automatically convert a voicemail message to text. The resulting text and a link to the audio of the recording is then emailed to the user. This simple demo provides functionality similar to commercial services such as VoiceCloud, Jott, and PhoneTag.

The demo works as follows. A user visits a webpage, enters their phone number and clicks the Call button, Twilio initiates an outgoing call to that number, the caller to leaves a recorded message, that messages is transcribed to text, and the text and a link to the audio is emailed to the user.

Concepts

This demo shows how to make outgoing calls using the Twilio REST API, how to use the TwiML <Record> verb to make an audio recording and to transcribe that recording to text.

Download

voicemailtranscribe.zip

Implementation

  • 1

    • The index page is a simple form that accepts a phone number and email address from the user.

      • howtos/voicemailtranscribe/index.php
        <h1>Voicemail transcription demo</h1>
        
        <h2 style="color: #ff0000"><?php echo htmlentities($_REQUEST['msg']); ?></h2>
        
        <h3>Please enter your phone number and email address<br/><br/>
        <form action="makecall.php" method="post">
        	Phone: <input type="text" name="number" /><br/>
        	Email: <input type="text" name="email" /><br/>
        	<input type="submit" value="Call me">
        </form>
        </h3>
        
        <i>You will called and asked to leave a voicemail message.  The voicemail will
        be transcribed using Twilio's transcription API and emailed to you in a
        few minutes.</i>
            

      The user enters a phone number and presses the Call button. The browser requests the makecall.php page which makes a request to the Twilio REST URL /2010-04-01/Accounts/ACCOUNT_SID/Calls (where ACCOUNT_SID is your Twilio account identifier) which initiate an outgoing call.

      To make the REST call we take advantage of the free PHP REST API library provided by Twilio. It simplified the the process of making HTTPS requests to Twilio and processing the responses. You can download a copy of the of the PHP REST library here. NOTE: If you would like to copy and use the code on this page there are several account specific variables you will need to fill in including AccountSid, AuthToken, and CallerID. For more information on making outgoing calls take a look at the REST Quickstart.

      • howtos/voicemailtranscribe/makecall.php
        <?php
        require "Services/Twilio.php";
        
        /* Set our AccountSid and AuthToken */
        $sid = "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        $token = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";
        
        /* Outgoing Caller ID you have previously validated with Twilio */
        $CallerID = 'NNNNNNNNNN';
        
        /* Instantiate a new Twilio Rest Client */
        $client = new Services_Twilio($sid, $token);
        
        /* Validate request */
        if (!isset($_REQUEST['number'])) {
            $err = urlencode("Must specify phone number");
            header("Location: .?msg=$err");
            die;
        }
        
        if (!isset($_REQUEST['email'])) {
            $err = urlencode("Must specify email address");
            header("Location: .?msg=$err");
            die;
        }
        
        if (!preg_match('/^[a-z0-9_.-]+@([a-z0-9_-]+\.)+[a-z0-9_-]{2,4}$/i', $_REQUEST['email'])) {
            $err = urlencode("Invalid email address");
            header("Location: .?msg=$err");
            die;
        }
        
        $url = "http://demo.twilio.com/voicemailtranscribe/makerecording.php?email="
        	. urlencode($_REQUEST['email']);
        
        /* make Twilio REST request to initiate outgoing call */
        try {
        
        	$call = $client->account->calls
        		->create($CallerID, $_REQUEST['number'], $url);
        
        	/* redirect back to the main page with CallSid */
        	$msg = urlencode("Calling... ".$_REQUEST['number']);
        	header("Location: .?msg=$msg&CallSid=" . $call->sid);
        
        } catch(Exception $e) {
        
            $err = urlencode($e->getMessage());
            header("Location: .?msg=$err");
        	die;
        
        }
        
        ?>    

      After initiating the call or throwing an error, the server redirects the client back to the main page.

  • 2

    • When the call is answered, Twilio makes an HTTP request to the makerecording.php page the link to which was specified as part of the REST request. The email address is included as a parameter in the URL so it is also passed as party of the request to makerecording.php.
  • 3

    • The makerecording.php page sent back Twilio TwiML with <Say> to read the voicemail greetings and a <Record> to record and transcribe the voicemail. The maxLength parameter tells Twilio to records a maximum of 30 seconds of audio.

      • howtos/voicemailtranscribe/makerecording.php
        <?php
            header("content-type: text/xml");
        
            if (!isset($_REQUEST['email'])) {
                echo "Must specify email address";
                die;
            }
            echo('<?xml version="1.0" encoding="UTF-8"?>');
        ?>
        <Response>
            <Say>Hello. This is a call from the Twilio voicemail transcription demo.
        Please leave a voicemail after the beep, and remember to speak clearly.</Say>
            <Record transcribe="true" transcribeCallback="<?php
                echo "transcribed.php?email=".urlencode($_REQUEST['email']); ?>"
                action="goodbye.php" maxLength="30" />
        </Response>
            

      Automatic speech-to-text transcription of the recording is accomplished using the transcribe attribute on the <Record> verb, The transcribe attribute tells Twilio to pass this recording to a speech-to-text engine and attempt to convert the audio to human readable text. More details are available in the <Record> verb documentation.

      There is an additional charge for each transcription. See the pricing page from more information.

  • 4

    • When the speech-to-text transcription is complete, Twilio will make an HTTP POST request to the URL specified in transcribeCallback -- a parameter of the <Record> verb -- with text of the transcription. The transcribed.php contains the code than handles the transcription callback and emails the text of the transcription and the URL of the recording to specified email address.

      • howtos/voicemailtranscribe/transcribed.php
        <?php
            if (!isset($_REQUEST['email'])) {
                echo "Must specify email address";
                die;
            }
            
            if (!isset($_REQUEST['RecordingUrl'])) {
                echo "Must specify recording url";
                die;
            }
            
            if (!isset($_REQUEST['TranscriptionStatus'])) {
                echo "Must specify transcription status";
                die;
            }
            
            if (strtolower($_REQUEST['TranscriptionStatus']) != "completed") {
                $subject = "Error transcribing voicemail from ${_REQUEST['Caller']}";
                $body = "New have a new voicemail from ${_REQUEST['Caller']}\n\n";
                $body .= "Click this link to listen to the message:\n";
                $body .= $_REQUEST['RecordingUrl'];
            } else {
                $subject = "New voicemail from ${_REQUEST['Caller']}";
                $body = "New have a new voicemail from ${_REQUEST['Caller']}\n\n";
                $body .= "Text of the Twilio transcribed voicemail:\n";
                $body .= $_REQUEST['TranscriptionText']."\n\n";
                $body .= "Click this link to listen to the message:\n";
                $body .= $_REQUEST['RecordingUrl'];
            }
            
            $headers = 'From: help@twilio.com' . "\r\n" .
                'Reply-To: help@twilio.com' . "\r\n" .
                'X-Mailer: Twilio';
            mail($_REQUEST['email'], $subject, $body, $headers);
        ?>    

      There you have it. A simple speech-to-text voicemail solution with a click-to-call interface.