PHP - Favorite Movie Trilogy Example

This example application is written in PHP and utilizes our PHP WebAPI Library and Limonade. You will need all three of these on your web server in order for this example to work; the WebAPI Library and Limonade files actually need to be in the same folder as your Tropo PHP application file, or the require portion of the application won't work (effectively killing the entire app).

The app is built to provide a different experience for the caller depending on the channel they come in on - either VOICE or TEXT. It assumes if the user is texting the app, they were provided instructions telling them what to do - possibly on a website or a flyer. In this case, the options are four different movie trilogies; the user is asked to select their favorite using an assigned keypad number. We need to define what to do when the user texts the app vs what to do when the user calls the app, which is done right at the start of the script.

The first portion of the application defines the required external elements - including our PHP WebAPI library and Limonade (lines 3 and 4 of Figure 7.0) - then defines the function the app will use if the user submits a valid choice over text (lines 7 through 29):

Figure 7.0

<?php

require 'tropo.class.php';
require 'lib/limonade.php';

// This is a helper method, used when the caller initially sends in a valid input over the text channel.
function valid_text(&$tropo, $initial_text) {
	
// Create a new instance of the Session object, and get the channel information.
$session = new Session();
$from_info = $session->getFrom();
$network = $from_info['channel'];	
		
// Welcome prompt.
$tropo->ask("Welcome to the Tropo PHP example for $network");


    // Provide a prompt based on the the initial_text value
    if ($initial_text == "1") 
        {$tropo->say("You picked Lord of the Rings.  Did you know Gandalf is also Magneto?  Weird.");
        }
    if ($initial_text == "2") 
        {$tropo->say("You picked the original Star Wars.  I hear Leonard Nimoy was awesome in those.");
        }
    if ($initial_text == "3") 
        {$tropo->say("You picked the Star Wars prequels.  Stop calling this number, Mr. Lucas, we know it's you.");
        }
    if ($initial_text == "4") 
        {$tropo->say("You picked the Matrix. Dude, whoa.");
        }
        
    // Tell Tropo what to do next. This redirects to the instructions under dispatch_post('/hangup', 'app_hangup').
    $tropo->on(array("event" => "continue", "next" => "favorite-movie-webapi.php?uri=hangup"));

    // Tell Tropo what to do if there's an error. This redirects to the instructions under dispatch_post('/incomplete', 'app_incomplete').
    $tropo->on(array("event" => "incomplete", "next" => "favorite-movie-webapi.php?uri=incomplete"));

}

The application pulls in information from the initial session (lines 10, 11 and 12 of Figure 7.0) for use in the initial welcome prompt (line 15), then provides unique responses for each choice (lines 17 through 29). It also tells Tropo what to do next - in this case, it would move on to the hangup resource (line 32) unless an error occurs server-side, in which case it would move on to the error resource (line 35).

That's just the "helper" method, however; the app really begins in the Figure 7.1:

Figure 7.1

dispatch_post('/start', 'app_start');
function app_start() {

    // Create a new instance of the Session object, and get the channel information.
    $session = new Session();
    $from_info = $session->getFrom();
    $network = $from_info['channel'];   

    // Create a new instance of the Tropo object.
    $tropo = new Tropo();
    
     // See if any text was sent with session start.
    $initial_text = $session->getInitialText();

    // If the initial text is a choice, skip the input collection and go right to results
    if(strlen($initial_text) == 1 && is_numeric($initial_text)) {
    valid_text($tropo, $initial_text);
    }
    
 else {

    // Welcome prompt.
    $tropo->say("Welcome to the Tropo PHP example for $network");

    // Set up options for input.
    $options = array("attempts" => 3, "bargein" => true, "choices" => "1,2,3,4", "mode" => "dtmf", "name" => "movie", "timeout" => 30);

    // Ask the caller for input, pass in options.
    $tropo->ask("Which of these trilogies do you like the best?  Press 1 to vote for Lord of the Rings, press 2 for the original Star Wars, 3 for the Star Wars prequels, or press 4 for the Matrix", $options);

    // Tell Tropo what to do when the user has entered input, or if there's an error. This redirects to the instructions under dispatch_post('/choice', 'app_choice') or dispatch_post('/incomplete', 'app_incomplete').
    $tropo->on(array("event" => "continue", "next" => "favorite-movie-webapi.php?uri=choice", "say" => "Please hold."));
    $tropo->on(array("event" => "incomplete", "next" => "favorite-movie-webapi.php?uri=incomplete"));
    
    }

    // Render the JSON for the Tropo WebAPI to consume.
    return $tropo->RenderJson();

}

This code is defined as our starting point by the URL set in the Tropo UI (see the Creating Your First Application chapter for more information on setting URLs - note that since we're using Limonade, you would need to define the end of the URL to include the resource name, like http://www.example.com/favorite-movie-webapi.php?uri=start). Much like the helper method earlier in the first code piece, it too pulls in session information for use (lines 5, 6 and 7 of Figure 7.1). However, before the welcome prompt (line 23), it checks to see whether any text was sent with the initial session (line 13) - if there was a value for initial_text, the app came across the TEXT channel. It then checks to see if the value was a valid one - a single, numeric digit (lines 16). If that matches, it then redirects to the valid_text function (line 17) - the one we defined in the very beginning (Figure 7.0).

If the channel was VOICE or the input was invalid, it moves on to ask the user to select their favorite movie trilogy and defines the keypad choices they can use to make their selection (line 29 of Figure 7.1). How many times it will ask for a valid input is defined by attempts earlier in the code (line 26 of Figure 7.1). If the user makes a valid selection, it moves on to the choice resource (line 32 of Figure 7.1), which is shown in Figure 7.2:

Figure 7.2

dispatch_post('/choice', 'app_choice');
function app_choice() {
    
    // Accessing the result object
    $result = new Result();
    $choice = $result->getValue();
    
    // Create a new instance of the Tropo object.
    $tropo = new Tropo();
    
    // Provide a prompt based on the value
    if ($choice == "1") 
        {$tropo->say("You picked Lord of the Rings.  Did you know Gandalf is also Mag knee toe?  Weird.");
        }
    if ($choice == "2") 
        {$tropo->say("You picked the original Star Wars.  I hear Leonard Nimoy was awe some in those.");
        }
    if ($choice == "3") 
        {$tropo->say("You picked the Star Wars prequels.  Stop calling this number, Mr. Lucas, we know it's you.");
        }
    if ($choice == "4") 
        {$tropo->say("You picked the Matrix. Dude, woe.");
        }

    // Tell Tropo what to do next. This redirects to the instructions under dispatch_post('/hangup', 'app_hangup').
    $tropo->on(array("event" => "continue", "next" => "favorite-movie-webapi.php?uri=hangup"));
    
    // Tell Tropo what to do if there's an error. This redirects to the instructions under dispatch_post('/incomplete', 'app_incomplete').
    $tropo->on(array("event" => "incomplete", "next" => "favorite-movie-webapi.php?uri=incomplete"));
    
    // Render the JSON for the Tropo WebAPI to consume.
    return $tropo->RenderJson();
}

The choice resource will look much like the valid_text "helper" method. It retrieves the user's choice from the result object sent back by Tropo (lines 5 and 6 of Figure 7.2) and reads off the appropriate prompt based on the value (lines 12 through 23). Once it's finished with the say, it moves on to hangup (line 26), shown in Figure 7.3:

Figure 7.3

dispatch_post('/hangup', 'app_hangup');
function app_hangup() {
    
    $tropo = new Tropo();
    
    $tropo->say("Thanks for voting!");
    $tropo->hangup();
    return $tropo->RenderJson();
}

Unless, of course, there's a server-side error - at which point it would have moved on to error:

Figure 7.4

dispatch_post('/error', 'app_error');
function app_error() {
    
    $tropo = new Tropo();
    
    $tropo->say("Something has gone wrong, please call back.");
    $tropo->hangup();
    return $tropo->RenderJson();
}

Last line just tells the app to run and you're good to go!

Figure 7.5

run();

Next Step: Node.js - Voice Recording Example

Check out the Behind the Scenes JSON if you're so inclined; if you want to see the complete application all put back together, it can be found on our Github. This blogpost may also be useful.

ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page

Behind the Scenes JSON - Volunteer Opportunities

| TOC

| Behind the Scenes JSON - Favorite Movie Trilogy