Twilio

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 up to five 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

• Receives a phone call and sends Caller ID 1
• Verifies the number and outputs TwiML to record the message 2
• Saves recording and sends Recording URL 3
• Places outgoing calls to all the user's contacts using REST 4
• Twilio calls each contact 5
• Outputs TwiML to Play the recorded message 6
• Play the recorded message 7

• 1

  • 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 "storenumbers.php";
      
      /* File Location for use in REST URL */
      $url = 'http://www.example.com/php/';
      
      /* Start TwiML */
      header("content-type: text/xml");
      echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
      
      /* Check to make sure that the user has contacts in the database */
      if(getNumbers($_REQUEST['Caller'])) { ?>
      
      <Response>
      	<Record action="<?php echo $url . 'broadcast.php?number=' .$_REQUEST['Caller'] ?>"/>
      	<Say>I did not receive a message</Say>
      </Response>
      	
      <?php } else { ?>
      
      <Response>
      	<Say>You have not registered any contacts</Say>
      </Response>
      
      	<?php
      }
      	
      ?>    

    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 "twilio.php";
      
      /* Twilio REST API version */
      $ApiVersion = "2010-04-01";
      
      /* Set our AccountSid and AuthToken */
      $AccountSid = "AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
      $AuthToken = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";
      
      /* Outgoing Caller ID you have previously validated with Twilio */
      $number = 'NNNNNNNNNN';
      
      /* Outgoing Number you wish to call */
      $outgoing = '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 TwilioRestClient($AccountSid, $AuthToken);
      
      if (!isset($_REQUEST['called'])) {
          $err = urlencode("Must specify your phone number");
          header("Location: index.php?msg=$err");
          die;
      }
      
      /* make Twilio REST request to initiate outgoing call */
      $response = $client->request("/$ApiVersion/Accounts/$AccountSid/Calls",
          "POST", array(
              "From" => $number,
              "To" => $outgoing,
              "Url" => $url . 'callback.php?number=' . $_REQUEST['called']
          ));
          
      if($response->IsError) {
          $err = urlencode($response->ErrorMessage);
          header("Location: index.php?msg=$err");
          die;
      }
      
      /* redirect back to the main page with CallSid */
      $msg = urlencode("Connecting... ".$_REQUEST['called']);
      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

      <?php
      require "twilio.php";
      require "storenumbers.php";
      
      /* Twilio REST API version */
      $ApiVersion = "2008-08-01";
      
      /* Set our AccountSid and AuthToken */
      $AccountSid = "AXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
      $AuthToken = "YYYYYYYYYYYYYYYYYYYYYYYYYYYYYYYY";
      
      /* Outgoing Caller ID you have previously validated with Twilio */
      $number = 'NNNNNNNNNN';
      
      /* File Location for use in REST URL */
      $url = 'http://www.example.com/php/';
      
      /* Instantiate a new Twilio Rest Client */
      $client = new TwilioRestClient($AccountSid, $AuthToken);
      
      /* @start snippet */
      
      /* Start TwiML */
      header("content-type: text/xml");
      echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
      
      if(!isset($_REQUEST['RecordingUrl'])){ ?>
      <Response>
      	<Say>Error: No URL</Say>
      </Response>
      	<?php die;
      }
      
      if(isset($_REQUEST['number'])){
      	$contacts = getNumbers($_REQUEST['number']);
      	if($contacts) {
      		foreach($contacts as $output) {
      			$response = $client->request("/$ApiVersion/Accounts/$AccountSid/Calls",
      			"POST", array(
      			"Caller" => $number,
      			"Called" => $output,
      			"Url" => $url . '/play.php?url=' .$_REQUEST['RecordingUrl']));
      		} ?>
      
      <Response>
      	<Say>Your message has been broadcast</Say>
      </Response>
      
      	<?php } else { ?>
      	
      <Response>
      	<Say>No Contacts could be found</Say>
      </Response>
      
      <?php }} /* @end snipp */ ?>    

    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");
      echo "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n";
      	
      if($_REQUEST['url']){ ?>
      
      <Response>
      	<Play><?php echo $_REQUEST['url'] ?></Play>
      </Response>
      
      <?php }	?>    

• 7

  • Twilio plays the recorded audio back to the caller