Helper Classes for using CloudVox API (with examples)

1_collect_phone.php

<?php
/*
 * Render a simple dialog asking for a caller's phone number.
 */


// Include CloudVox JSON helper classes.
include('cloudvox-json-http-classes.php');

$speak = new Speak("Welcome to my demo application.");
$playback = new Playback("enter-phone-number10");
$getDigits = new GetDigits(10,5);
$getDigits->url = "http://somehost.org/2_verify.php";
	
// Statically call the renderJSON() method of the Output object to write out JSON to CloudVox.
Output::renderJSON($speak, $playback, $getDigits);

?>

2_verify.php

<?php
/*
 * Verify that the caller entered the correct telephone number.
 */

// Include CloudVox JSON helper classes.
include('cloudvox-json-http-classes.php');

// Instantiate a new CloudVox response object.
$response = new CloudVoxResponse();
	
// Insert spaces in between each digit in the phone number to improve TTS readback.
$phoneNumber = implode(" ", str_split($response->result));
	
$playback_youentered = new Playback("you-entered");
$speak_phone = new Speak($phoneNumber);
	
$playback_correct = new Playback("if-correct-press");
$playback_press1 = new Playback("press-1");
	
$playback_notcorrect = new Playback("if-this-is-not-correct");
$playback_press2 = new Playback("press-2");
	
$getDigits = new GetDigits(1,5);
$getDigits->url = "http://somehost.org/3_confirm.php";

// Statically call the renderJSON() method of the Output object to write out JSON to CloudVox.	
Output::renderJSON($playback_youentered, $speak_phone, $playback_correct, $playback_press1, $playback_notcorrect, $playback_press2, $getDigits);

?>

3_confirm.php

<?php
/*
 * Redirect or end the call based on the caller's selection.
 */

// Include CloudVox JSON helper classes.
include('cloudvox-json-http-classes.php');

// Instantiate a new CloudVox response object.
$response = new CloudVoxResponse();
	
// We need to create playback elements for both confirmation scenarios.
$playback_sorry = new Playback("im-sorry");
$playback_try_again = new Playback("please-try-again");
$include = new IncludeStep("http://somehost.org/1_collect_phone.php");
	
$playback_thanks = new Playback("thanks-for-calling-today");
$playback_goodbye = new Playback("goodbye");
$hangup = new Hangup();
	
// If the caller confirmed their response, end the call, if not start over.
if($response->result != 1) {
	Output::renderJSON($playback_sorry, $playback_try_again, $include);
}
else {
	Output::renderJSON($playback_thanks, $playback_goodbye, $hangup);
}

?>

cloudvox-json-http-classes.php

<?php

/*
 * PHP Classes for interacting with the CloudVox API.
 * http://help.cloudvox.com/faqs/getting-started/http-api
 * 
 * Copyright 2010 Mark J. Headd.
 * www.voiceingov.org
 */

/**
 * Base class for all CloudVox API steps.
 * This class includes a __set() method to allow
 * overloading, used for creating/assigning optional
 * properites for each class.
 *
 */
class stepBase {
	public function __set($attribute, $value) {
		$this->$attribute= $value;
	}	
}

/**
 * Join the call into a conference, or create a new conference.
 *
 */
class Conference extends stepBase {
	public $name = "Conference";
	public $action;
	public $room;
	
	/**
	 * Class Constructor
	 *
	 * @param $action
	 * @param $room
	 */
	public function __construct($action, $room) { 
		$this->action = $action;
		$this->room = $room;
	}		
}

/**
 * Connect existing caller to a traditional phone number (PSTN), SIP phone extension, or SIP recipient. 
 * Existing caller will hear ringing and answer, if any. 
 * Processing of remaining steps will pause until call has completed, then resume.
 *
 */
class Dial extends stepBase {
	public $name = "Dial";
	public $destination;
	
	/**
	 * Class Constructor
	 *
	 * @param $destination
	 */
	public function __construct($destination) {
		$this->destination = $destination;
	}
}

/**
 * Send touchtone digits as if the caller had pressed them. Useful for navigating menu trees.
 *
 */
class DTMF extends stepBase {
	public $name = "DTMF";
	public $digits;
	
	/**
	 * Class Constructor
	 *
	 * @param $digits
	 */
	public function __construct($digits) {
		$this->digits = $digits;
	}
}


/**
 * Collect keypad digit presses from caller.
 *
 */
class GetDigits extends stepBase {
	public $name = "GetDigits";
	public $max;
	public $timeout;
	
	/**
	 * Class Constructor
	 *
	 * @param $max
	 * @param $timeout
	 */
	public function __construct($max, $timeout) {
		$this->max = $max;
		$this->timeout = $timeout;
	}
}

/**
 * Immediately disconnect a call, rather than continuing until all queued steps have been executed.
 *
 */
class Hangup extends stepBase { 
	public $name = "Hangup";
}

/**
 * Retrieve and execute steps from another URL/
 *
 */
class IncludeStep extends stepBase {
	public $name = "Include";
	public $url;
	
	/**
	 * Class Constructor
	 *
	 * @param $url
	 */
	public function __construct($url) {
		$this->url = $url;
	}
}

/**
 * Hit a URL after call ends. Useful for post-call processing and cleanup.
 *
 */
class OnHangup extends stepBase {	
	public $name = "OnHangup";
	public $url;
	
	
	/**
	 * Class Constructor
	 *
	 * @param $url
	 */
	public function __construct($url) {
		$this->url = $url;
	}
}

/**
 * Play a file by filename.
 *
 */
class Playback extends stepBase {	
	public $name = "Playback";
	public $filename;
	
	/**
	 * Class Constructor
	 *
	 * @param $filename
	 */
	public function __construct($filename) {
		$this->filename = $filename;
	}
}

/**
 * Record caller audio to a file, such as for voicemail, voice greeting, or annotation. 
 * Recording continues until caller presses "#" or maxduration or silence thresholds are reached.
 *
 */
class Record extends stepBase {
	public $name = "Record";
	public $filename;
	
	/**
	 * Class Constructor
	 *
	 * @param $filename
	 */
	public function __construct($filename) {
		$this->filename = $filename;
	}
}

/**
 * Speak a phrase using a human-sounding text-to-speech robot.
 *
 */
class Speak extends stepBase {
	public $name = "Speak";
	public $phrase;
	
	/**
	 * Class Constructor
	 *
	 * @param $phrase
	 */
	public function __construct($phrase) { 
		$this->phrase = $phrase;
	}
}

/**
 * Class to render JSON output to CloudVox platform.
 *
 */
class Output {
	public static function renderJSON() {
		header("Content-type: application/json");
		echo json_encode(func_get_args());
	}
}

/**
 * Class to wrap CloudVox response.
 *
 */
class CloudVoxResponse {
	
	/*
	 * Unique ID identifying the call.
	 */
	public $call_id;
	
	/*
	 * The result of any step that collected data from the caller.
	 */ 
	public $result;
	
	/*
	 * Caller ID (when available).
	 */
	public $callerid;	
	
	/*
	 * Caller ID Name (when available).
	 */
	public $calleridname;
	
	/**
	 * Class Constructor
	 *
	 */
	public function __construct() {
		$this->call_id = isset($_REQUEST["call_id"]) ? $_REQUEST["call_id"] : null;
		$this->result = isset($_REQUEST["result"]) ? $_REQUEST["result"] : null;
		$this->callerid = isset($_REQUEST["callerid"]) ? $_REQUEST["callerid"] : null;
		$this->calleridname = isset($_REQUEST["calleridname"]) ? $_REQUEST["calleridname"] : null;
	}	
}

?>