Call Tracking

A call tracking application allows you to collect metrics about your phone calls so you can monitor their effectiveness and optimize marketing. Using Twilio, you can record every call as well as track information such as what number was dialed, what time of day it was dialed, the duration of the call, and the geographic location of the caller.

Usage

A twilio phone number is provisioned (see HowTo - Phone Number Search API) and its voice url is set to the "handle_incoming_call.php" script . When a call is made to that number, Twilio makes a request to your application's voice url for instructions on how to handle the call. The call tracking application stores the information Twilio sends about the call in a database and then connects the incoming call to an operator's phone. After the call to the operator is completed, Twilio makes another call to the application, which updates its database with the status of the 2nd leg of the call. And finally, if you want to deprovision a number used in a temporary call tracking campaign (and thereby no longer have to pay for it), please see this documentation.

Concepts

This HowTo shows how to receive calls using Twilio, how to capture call information in a database, and how to use the TwiML <Dial> verb.

Download

Twilio-Call-Tracking.zip, part of a larger Twilio Call Tracking example

Implementation

• Lead dials a Twilio number and Twilio POSTs information to your application 1
• Your application saves Twilio call information in local database 2
• Your application sends TwiML instructions to Dial an agent 3
• Lead and agent have a conversation until one of them disconnects 4
• Twilio requests the Dial action URL and sends information about the second call leg 5

• 1

  • Our Twilio number's voice URL is set to handle_incoming_call.php, and when someone calls the number Twilio will request this page with the standard TwiML request parameters.

    • howtos/call_tracking/handle_incoming_call.php

      <?php
      	require_once('./include/config.php');
      	header('Content-type: text/xml');
      	$db = new DB();
      	$db->save_call();
      ?>
      <Response>
      	<Dial action="record_call.php" method="GET" record="true"><?php echo(AGENT_NUMBER);?></Dial>
      </Response>
          

• 2

  • The application uses the save_call() method to read the parameters sent by Twilio, and save them to a new record in a local database.
  • howtos/call_tracking/db.php

    
    		function save_call() {
    			//http://www.twilio.com/docs/api/twiml/twilio_request#synchronous-request-parameters
    			$CallSid = $_REQUEST['CallSid'];
    			$AccountSid=$_REQUEST['AccountSid'];
    			$CallFrom=$_REQUEST['From'];
    			$CallTo=$_REQUEST['To'];
    			$CallStatus=$_REQUEST['CallStatus'];
    			$ApiVersion=$_REQUEST['ApiVersion'];
    			$Direction=$_REQUEST['Direction'];
    
    			if (isset($_REQUEST['FromCity'])){
    				$FromCity=$_REQUEST['FromCity'];
    				$FromState=$_REQUEST['FromState'];
    				$FromZip=$_REQUEST['FromZip'];
    				$FromCountry=$_REQUEST['FromCountry'];
    			} else {
    				$FromCity="";
    				$FromState="";
    				$FromZip="";
    				$FromCountry="";
    			}
    			$ToCity=$_REQUEST['ToCity'];
    			$ToState=$_REQUEST['ToState'];
    			$ToZip=$_REQUEST['ToZip'];
    			$ToCountry=$_REQUEST['ToCountry'];
    
    			$stmt = $this->db->prepare('INSERT INTO calls (DateCreated,CallSid,AccountSid,CallFrom,CallTo,CallStatus,ApiVersion,Direction,FromCity,FromState,FromZip,FromCountry,ToCity,ToState,ToZip,ToCountry) VALUES (DATETIME(\'now\',\'localtime\'),?,?,?,?,?,?,?,?,?,?,?,?,?,?,?)');
    			$vars=array($CallSid,$AccountSid,$CallFrom,$CallTo,$CallStatus,$ApiVersion,$Direction,$FromCity,$FromState,$FromZip,$FromCountry,$ToCity,$ToState,$ToZip,$ToCountry);
    			$stmt->execute($vars);
    		}
        

• 3

  • The application responds in TwiML to Twilio's request using the Dial verb. This instructs Twilio to dial another number and connect it with the incoming call.

    • howtos/call_tracking/handle_incoming_call.php

      <?php
      	require_once('./include/config.php');
      	header('Content-type: text/xml');
      	$db = new DB();
      	$db->save_call();
      ?>
      <Response>
      	<Dial action="record_call.php" method="GET" record="true"><?php echo(AGENT_NUMBER);?></Dial>
      </Response>
          

• 4

  • The caller and agent speak until either party hangs up the call.

• 5

  • Twilio requests the URL entered as the 'action' parameter of the Dial verb (from step 3), and Twilio sends the extra dial action parameters describing the outcome of the second leg of the call. The application updates the call record from step 2 with the additional information, then returns a minimal TwiML response.

    • howtos/call_tracking/record_call.php

      <?php
      	require_once('./include/config.php');
      	header('Content-type: text/xml');
      	$db = new DB();
      	$db->save_dialed_call();
      ?>
      <Response/>