Get Started

Voice Message Broadcast

Voice broadcast connects users to their audiences. Broadcast recorded messages instantly and easily. All it takes is a call.

Usage

A user signs up for the service, specifying his/her phone number and a set of phone numbers that will receive his/her broadcast messages. When the user calls the service, he/she is prompted to record a message. On completion, Twilio broadcasts this message to that user's specified contacts

Concepts

This demo demonstrates initializing a call using the Twilio REST API and creating TwiML call logic using the <Play>, <Say> and <Record> verbs.

Download

broadcast.zip

Implementation

  • 1

    • User accesses index.php and enters numbers of people to reach. When ready, user dials in and Twilio receives a call to the broadcast service phone number. After answering the call, Twilio hands over the call to record.php, passing along call data, such as Caller ID, via POST
  • 2

    • First, we check if the user's phone number is in the database using the getNumbers function. If not, the user is told to register his/her phone number with the service. We provide a sign up form for our demo, but registrations can be handled in any manner that suits your needs.

      The action attribute on the record specifies the url that Twilio will query after the recording in finished. We add the user's number into the URL's query string for use later on.

      • howtos/broadcast/record.php
        <?php
        require "Services/Twilio.php";
        require "storenumbers.php";
        
        /* File Location for use in REST URL */
        $url = 'http://www.example.com/php/';
        
        /* Start TwiML */
        header("content-type: text/xml");
        $response = new Services_Twilio_Twiml();
        
        /* Check to make sure that the user has contacts in the database */
        if (getNumbers($_REQUEST['From'])) {
        	$response->record(array(
        		'action' => $url . 'broadcast.php?number=' . $_REQUEST['From']
        	));
        	$response->say('I did not receive a message');
        } else {
        	$response->say('You have not registered any contacts');
        }
        print $response;
        ?>
            

      Once the user presses submit, the form sends the number (via POST) to makecall.php. Makecall.php uses the Twilio REST Client to call the third party's phone number.

      • howtos/clicktocall/makecall.php
        <?php
        require "Services/Twilio.php";
        
        /* Set our AccountSid and AuthToken */
        $AccountSid = "AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
        $AuthToken = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";
        
        /* Your Twilio Number or an Outgoing Caller ID you have previously validated
        	with Twilio */
        $from= 'NNNNNNNNNN';
        
        /* Number you wish to call */
        $to= 'MMMMMMMMMM';
        
        /* Directory location for callback.php file (for use in REST URL)*/
        $url = 'http://www.example.com/clicktocall/';
        
        /* Instantiate a new Twilio Rest Client */
        $client = new Services_Twilio($AccountSid, $AuthToken);
        
        if (!isset($_REQUEST['called']) || strlen($_REQUEST['called']) == 0) {
            $err = urlencode("Must specify your phone number");
            header("Location: index.php?msg=$err");
            die;
        }
        
        /* make Twilio REST request to initiate outgoing call */
        $call = $client->account->calls->create($from, $to, $url . 'callback.php?number=' . $_REQUEST['called']);
        
        /* redirect back to the main page with CallSid */
        $msg = urlencode("Connecting... ".$call->sid);
        header("Location: index.php?msg=$msg");
        ?>
            

      To store and retrieve phone numbers, we use the putNumbers and getNumbers functions found in storenumbers.php. For this example, these functions interface with a text file, numbers.txt. Phone numbers are stored as lists of comma separated values. However, the text file storage system can be easily interchanged with more robust databases, like MySQL or Oracle. Storenumbers.php contains the necessary implementation details. IMPORTANT: If you plan to implement voice broadcast, using a text file as your database storage is discouraged for security reasons.

  • 3

    • Twilio records and saves the message in the cloud. Next, it sends the URL of the recording to broadcast.php via POST
  • 4

    • Using the number parameter we stored in the URL, we look up the contacts the user has registered. If the the user isn't in the database, we output TwiML notifying the user that his/her message will not be broadcast. If contacts are found, we loop over the array of contacts' numbers and place outgoing calls to each number using the Twilio REST API. Our action URL is play.php, which will play our recording.

      • howtos/broadcast/broadcast.php
        if (empty($_REQUEST['RecordingUrl'])) {
        
        	// Warn the caller if we didn't find a recording URL
        	$response = 'Error: No URL';
        
        } else if (isset($_REQUEST['number'])) {
        
        	// Attempt to retrieve contacts
        	$contacts = getNumbers($_REQUEST['number']);
        
        	if (empty($contacts)) {
        		// Warn the caller if we didn't find any contacts
        		$response = 'No Contacts could be found';
        
        	} else {
        
        		// Call each contact
        		foreach ($contacts as $output) {
        			try {
        				$url = $urlbase . '/play.php?url=' . $_REQUEST['RecordingUrl'];
        				$client->account->calls->create($number, $output, $url);
        			} catch (Exception $e) {
        				// log error
        			}
        		}
        
        		$response = 'Your message has been broadcasted';
        	}
        }
        // Render TwiML
        header('content-type: text/xml');
        print $response;
            

      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 REST PHP libraries here *NOTE: If you would like to copy and use this code 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

  • 5

    • Twilio rings each contact on the user's list
  • 6

    • We output a new TwiML response to play back to recording

      • howtos/broadcast/play.php
        <?php 
        
        header("content-type: text/xml");
        if ($_REQUEST['url']) {
        	$response = new Services_Twilio_Twiml();
        	$response->play($_REQUEST['url']);
        	print $response;
        }
            
  • 7

    • Twilio plays the recorded audio back to the caller