PHP

Building KooKoo applications in php is as easy as it gets.

response.php is a KooKoo php library that has been designed to help you create KooKoo markup faster. It is not mandatory for you to use the KooKoo PHP library to create the markup. Plain XML is sufficient.

In order to use the KooKoo php library, just download KooKoo PHP library and include it in your source code.

KooKoo php library has two main classes:

Response: This is the root tag

collectdtmf: Collect user input from your callers

Response is the main class. To talk to KooKoo you have to first create a response object.

    1  $r = new Response(); 

If you want to maintain session through the response object you instantiate it with a state variable

    1  $r = new Response("start"); 

Once a response object is created, you can inform KooKoo to do several tasks on your behalf.For each task there is corresponding method in the Response object. The supported tasks and their corresponding methods are given below:

playtext: Play some text to your callers
playaudio: Play some audio to your callers
Send Sms: Tells KooKoo to send an SMS to a specified number.(Available only to paid users)
record: Record caller conversation
Hangup: Tells KooKoo to hangup the call.
dial: Make an outbound call (Available only to paid users)

Play text

Description:Tells KooKoo to play some text using the default text to speech engine.The characters usage of playtext tag is limited to 100 characters.

Method:addPlayText($text) 
Arguments:The text to play 
Example:$r->addPlayText("I love KooKoo"); 

Play audio

Description: Tells KooKoo to play an audio file.

Method:addPlayAudio($url) 
Arguments:The URL of the audio to play 
Example:$r->addPlayAudio("http://www.example.com/test.wav"); 

Send sms

Description:Tells KooKoo to send an SMS to a specified number.

Method: sendSms($text,$number) 
Arguments:The text of the sms message (should be less that 160 characters) 
and the mobile number to send the sms to. 
Example:$r->sendSms("This is an sms message",919000455345); 

Record

Description: Tells KooKoo to play a beep to the caller and record his message.

The URL of the recorded message will be sent back to your application. 
Method: addRecord($filename,$format,$silence,$maxduration,$option) 
Arguments: 
filename:The name to be given to the recorded audio. 
format:The format of the recorded audio. Right now only wav is supported. 
silence:Number of seconds of silence before we assume the caller has finished recording. 
Default value is 2 secs. 
maxduration:Maximum number of seconds to allow recording. Default value is 30 secs. 
option:Any additonal options to be provided to the record function. 
Right now this parameter is not used.So you can leave it. 
Example:$r->addRecord("test.wav"); 

Hangup

Description: Tells KooKoo to hangup the call.

    1  Method:addHangup() 
    2  Example:$r->addHangup(); 

Collecting user input

Description: In KooKoo collecting user input is handled by the collectdtmf tag. Since the collectdtmf tag is a complex tag with other tags nested inside it, we have a CollectDtmf object to handle the collectdtmf tag. If your program needs to collect user input, first instantiate the CollectDtmf object

    1  $cd=new CollectDtmf(); 

You can set the following attributes on the CollectDtmf object
1.max digits: The maximum number of digits to collect from the user before stopping

    1  $cd->setMaxDigits("4");//This will tell KooKoo to collect 4 digits and return 

2.terminating character: Specify the terminating character which when pressed will tell KooKoo to stop accepting user input and return.

    1  $cd->setTermChar("#");//This means that when the user presses #, 
    2  kookoo stops accpeting user input and return the digits pressed so far. 

3.time out: The number of milliseconds to wait for an user to input a digit.If the user does not enter any digit for the specified amount of time, KooKoo assumes that the user has finished entering the digits and returns the digits entered so far to your application.

    1  $cd->setTimeOut("2000");//Time out is now set to 2 seconds. 

You can also add playtext and playaudio tags to the collectdtmf. These will be played as prompts to the user prompting him to enter input. The format of the addPlayText and addPlayAudio methods are same as that of the Response object.

    1  $cd->addPlayText("Please enter your pin number"); 

Once all the attributes are set to the CollectDtmf object we add the object to the Response.

    1  $r->addCollectDtmf($cd); 

So once the response object has been prepared with all the necessary actions, we send the response object to KooKoo

    1  $r->send(); 

KooKoo will receive the Response object, perform the actions specified and return results if there are any. Your application receives the results, processes them and creates another Response object if necessary. This flow continues until you are finished with your application. To put this all together, an example application, Adder, is explained below.

adder.php

<? php 
session_start(); 
require_once("response.php"); 
//you can download response.php from kookoophp.zip file located below 
$r = new Response();//create a new response object for your application 

Now you are ready to receive requests from the IVR. A general user scenario is given below.

Step 1: A customer calls your phone number.

Step 2: KooKoo receives the call and informs us of the new call at the URL we have specified in our KooKoo dashboard.Let us say our URL is http://www.yoursite.com/adder.php

Step 3: The PHP at the URL receives the request. We need to handle the message from KooKoo about the new call.

KooKoo communicates with our application by posting GET requests to our web server and passing request parameters. Add the following to adder.php to handle the KooKoo new call message.We recieve the call and ask KooKoo to interact with the caller to get the first number to calculate.

if($_REQUEST['event']=="NewCall") 
{ 
    $cd = new CollectDtmf();//Create Collect DTMF object 
    //which accepts dtmf for your application 
    $cd->setTermChar("#");//(The terminating chracter. KooKoo will stop accepting input 
    //after receiving this character.Default value is '#') 
    $cd->setTimeOut("4000");( KooKoo will wait for '4000' milliseconds for the 
    //user to enter some input.Default value is 4000 (4 seconds)). 
    $cd->addPlayText("welcome to adder.Please enter your first number.Terminate with hash"); 
    //addPlayText function used to play the prompts in your application 
    $r->addCollectDtmf($cd); 
    //import the collect dtmf to response object 
    //now add the Collect DTMF object to response object 
    //(Basically Tracking the DTMF input on single response object) 
    $_SESSION['state'] = "firstNumber"; 
    //Setting our current state to indicate that we are collecting first number. 
    //We will use the session variables to track our flow. 
    $r->send(); 
    //send the XML back to KooKoo 
} 

Step 4: KooKoo will play the specified text, collect the user input and inform us again at our URL. To handle that event add the following code sequentially

else if ($_REQUEST['event']=="GotDTMF" && $_SESSION['state'] == "firstNumber") 
{//here the event is GotDTMF(This Events Are Requested from KooKoo) 
    $first = $_REQUEST['data'];//store the first number 
    $cd = new CollectDtmf();//Create Collect DTMF object 
    //which accepts dtmf for your application 
    $cd->setTermChar("#");//(The terminating chracter. KooKoo will stop accepting 
    //input after receiving this character.Default value is '#') 
    $cd->setTimeOut("4000");( KooKoo will wait for '4000' milliseconds for the user to 
    //enter some input.Default value is 4000 (4 seconds)). 
    $cd->addPlayText("Please enter the Second number.Terminate with hash"); 
    //addPlayText function used to play the prompts in your application 
    $_SESSION['firstNumber']=$first;//store first number in session variable 
    $_SESSION['state'] = "secondNumber"; 
    //Setting our current state to indicate that we are collecting second number. 
    //We will use the session variables to track our flow. 
    $r->addCollectDtmf($cd); 
    $r->send();//send the XML back to KooKoo 
} 

Step 5: KooKoo will collect the second number and inform us. To handle this event add the following code sequentially.

else if ($_REQUEST['event']=="GotDTMF" && $_SESSION['state'] == "secondNumber") 
{   //here the event is GotDTMF(This Events Are Requested from KooKoo) 
    $second = $_REQUEST['data'];//store the second number 
    $total = $_SESSION['firstNumber']+$second; 
    $r->addPlayText("your total is $total"); 
    //addPlayText function used to play the prompts in your application 
    $r->addHangup();//stops the call 
    $r->send();//send the XML back to KooKoo 
} 
?> 

Click to download

kookoophp

The KooKoo PHP Library makes it easy to write KooKoo songs without having to touch XML.

USAGE:

There are two main classes. Response and CollectDtmf. First create a response object and append any tags to it.Since CollectDtmf is a complex tag we have a seperate Class for it. To append a collectdtmf tag, first create a collectdtmf object and then append that object to the response tag.

NetWay Labs Reading Material

Friday, September 2, 2011

Koo Koo PHP

PHP