Prophecy 9.0 Development Guide

| TOC

Introduction to the Prophecy Designer

Tutorial: Designer Integration Tutorial Part 3 - HTTP Request

This tutorial is based on things we did in the last few tutorials, so if you haven't yet completed them you'll want to check them out.

In the last few tutorials, you learned how to setup a basic project that greets your caller and presents them with a few choices. Now you're going to create a project that not only records your caller, but sends that recording to a server side script.

Step 1: Create a New Project

First, we'll need to open up Designer and create a new project. As always, we'll need to give our project a unique name and description.

Step 2: Record Step

Initially, you're given a prompt step named Start. For this scenario, delete the Record step as this step is redundant (i.e., it allows you to play an announcement to your caller). Click on the step and select Remove.

Once you remove the Start step, click the Initial. This step has only one option, our starting step. Right now, it's not set to anything, nor do we have any step to go to, besides hangup, so let's create one. Click the blue plus symbol to bring up the step creator dialog. Let's type in Record Caller for our step name and, in the pull down, select Record as the step type. In our call flow diagram we should see the Initial Step pointing towards our new Record Caller step.

Click our new recording step to bring us into the step editor dialog. We'll need to add a little audio to tell our callers what they need to do, so click New Audio.

Next, click on the Record Settings tab. Here we'll need to set the maximum time to allow our callers to talk in seconds, and whether or not to play a beep to our callers to signify to start recording. We can also select to queue our recording for transcription and whether or not to store the recording locally in the recordings directory. Note: If you specify Queue for Transcription, recordings will not be pushed to your recordings directory until after all outstanding transcriptions have been satisfied. You can listen to and transcribe any pending recordings by clicking the Transcription link on the Designer menu.

For now, let's select Play Beep and a Max Record Time of 30 seconds and uncheck the other two. Since you're sending your recording to our server side, you won't need a locally stored copy.

Step 3: Yes/No Step

Let's give your caller a chance to re-record, just in case they didn't like the sound of their own voice the first time. Return to the Initial Prompt tab and click the plus button next to Destination. Select Yes/No as the Step Type and name it "Verify Recording." Clicking Save twice will bring you back to our updated call flow diagram.

Click New Audio and enter "Your recording was" and click OK. Some of you are probably thinking, "Hey! That's a sentence fragment!" But the sharp ones know where I'm going with this. We're going to play the recording back to the caller. How, you say? Read on, my inquisitive little friends.

Click Add Data and drop down the Data Variable list. You should now see a couple variables from our Record Caller step. Select the one with (RECORDING_FILE) next to it and check the box next to Audio URL, as you'll be playing back an audio file.

Next, click on the Caller Choices tab. Double click NO and select Record Caller as our Destination. This will send our caller back to re-record their message if they decide against saving those mean things they said about you the first time. Now, double click the YES option.

Step 4: Integration Step

Once the caller has decided they want to save their recording, you'll need to save it for them. Click the plus next to Route Calls To:, select Integration as the Type and name your step "Upload Audio." Click Save a few times and we'll be back at our call flow diagram. Select our newly created Upload Audio step.

We're going to be sending this to our server side script to take care of the business end of this call, so select HTTP Request as the Integration Type. We'll get into Web Services in a later tutorial, so don't get so antsy. We'll need to set everything up, so click Configure.

First, we'll want to enter the URL to our PHP script that will catch your audio file and save it locally. For Method, you'll need to select Post since you're sending an audio file here, and GET just won't do the trick. For Response Type, leave it as String, as this is the type you're expecting returned from our server side. Designer will take this value and store it in a project level variable as a String, so it's available for later use. You're probably wondering how Designer knows if everything went well in the step. First thing it'll check is the HTTP headers. If you get a 200 or 204 OK response and our response matches our Response Type, you're good to go, and Designer will return Successful. If you get an HTTP response in the 400-500 range, Designer will return a Failed event.

Next, you'll pass some variable/value pairs to the server, so you'll create and name those here. Click Add, and create parameters named file and callerid. You'll Populate this with a value in the next step, so click OK.

Once you're done there, you'll be taken back to your main Integration window. Here is where you'll define what values get sent along with your variables when you perform the HTTP request. You'll no doubt notice that your parameters now appear in this window along with an Add Data button. Click Add Data next to the file parameter. You'll want to populate this one with the actual recording you want to send, so drop down your Data Variable listing and select Record Caller(RECORDING_FILE) and click OK.

Our next parameter, callerid, is self explanatory, but your variable name is not. Click Add Data and select ANI here. ANI stands for Automatic Number Identification – or more commonly – caller ID. You may also notice DNIS, or dialed number identification service. This refers to the number our caller dialed to get here, or the called ID.

We're almost done, but don't click Save just yet. First, click on the Select Destinations tab. You'll want to branch your project depending on what response you got back from the webserver. Click the plus sign next to Successful Data Retrieval and create a Prompt step named Success. Do the same for Failure to Retrieve Data, but name this one Failure. Now you're ready to save this step and move on.

Back at our Call Flow diagram, you'll need to fix up your new Success and Failure steps properly. Click the Edit Step pull down and select Success. This is just a simple Prompt step that will let your callers know everything went A-OK. Click New Audio and type in a quick message letting the caller know their message was saved and to, "have a great day," because that's the polite thing to do. Click OK and stroll down to the Next Destination drop down. We're all done here and there's nothing else to see, so let's give our caller the boot – we already gave them a fond farewell, so they knew this was coming. Go ahead and click the drop down and select "Hangup" and click Save.

Wash. Rinse. Repeat. Let's do it one more time. Click Edit Step and select Failure. You've gotta let your caller know something went awry and they should probably give you a call later to try again. Add New Audio and send them off with a polite but firm message - it's OK, Grandma still thinks you're special. Select Hangup as your Final Destination™ and click Save.

Annnnnnnnd we're back. Everything should look spiffy in our Call Flow diagram and we shouldn't see any errors on our Project Menu. If there are then someone's had a few too many drinks, and there's a good chance that person is me.

Step 5: The Server Side of Life

Last but certainly not least, you'll need a little server scripting to grab your data and save it accordingly. Below is a little bit of PHP that'll do the trick. Save this to a text file with a .PHP extension or simply download it from the link below and place it on your favorite PHP enabled webserver. You'll want to create a subdirectory called "upload" for the files to be saved in.



<?php



   // get our caller id to help identify the recording

   $callerid = $_REQUEST['callerid'];





  if ($_FILES["file"]["error"] > 0)

    {

    // oops, something went wrong. let's let our app know

    header("HTTP/1.1 500 Internal Server Error");

    echo "Return Code: " . $_FILES["file"]["error"] . "<br />";

    }

  else

    {

	// copy our temp file to our real file name and save it on the server.

      move_uploaded_file($_FILES["file"]["tmp_name"],

      "upload/" . $callerid . "-" . date("His") . ".wav");





    }



?>

This dirty little example will check to make sure there aren't any funky errors with your file. If there is, it'll return an HTTP 500 header to our Designer app to let your caller know everything didn't go down as planned. Assuming all is well, this will take your file and save it in the upload directory with the naming scheme: [callerid]-[HHmmss].wav.

Step 6: Publish

Our project is now complete, so let's click Publish.

Now you'll publish your new project and map it to a number in your Management Console. Go to the Project Menu and click Publish. As long as there are no errors you will get a Publish Succeeded message.

Return to the Management Console and add our Designer project as an application. Your project is now ready for you to call in and test it.

All that's left is to call our new app. Start your favorite SIP Phone. Under dial string, we'll want to change the current dial string, e.g. sip:user@127.0.0.1 to the route we just created, e.g. sip:designer@127.0.0.1 and click "Dial."

Don't feel like going through all the hoops? Download the code directly here and import it into Designer.

Designer tutorial source code

Ready for the next step? In the next tutorial, we'll show you how to integrate a Web Service to create a truly useful Designer project.

ANNOTATIONS: EXISTING POSTS

joseg

11/10/2009 6:02 PM (EST)

Is it possible to save the file in "raw" format, not as a wave?

voxeoJason

2/17/2010 1:34 PM (EST)

Hi,

I would like to offer up my sincerest apology in the delay in our response. However I would like to clarify that once a user records a message, you're looking to push the file off in a different format other than .wav correct?
If this is the case, unfortunately Designer will only push files out in that format. However you may be able to convert those files by sending them off to a serverside script that would perform the function.

Regards,

Jason Sewell
Voxeo Support

voxeoJason

2/17/2010 2:20 PM (EST)

Hi,

I would also like to clarify if you're looking to push out headerless audio. If you can let us know what your end goal is we can certainly assist you in achieving it.

Regards,

Jason
Voxeo Support

Hello World - Part II

| TOC

| Integration - Web Services