Voxeo Developers Corner

Lately, the Voxeo Designer platform has become increasingly popular. However, it can be somewhat limited in terms of call control. Customers who are used to a combination of CCXML and VoiceXML may be turned away by this idea. Well, fear not, as we can easily integrate CCXML and Designer now, adding that game-changing call control aspect that CCXML brings to the table. Why use a CCXML front end, you say? Well, lots of reasons. CCXML brings call control, conferencing, whisper dialogs, hold dialogs, as well as the ability to pass in parameters to your Designer application. Whether it’s “you have a call from John Smith, press 1 to accept this call,” or a simple repeating hold music dialog, it is now possible with Designer dialogs.

So now let’s take a look at how we put it all together. Let’s assume that you already have a basic Designer application established. At this point, we don’t care what it does. Now, we need to write a CCXML front end for it.

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">
  <var name="myDialogID"/>
  <eventprocessor>

    <transition event="connection.alerting">
      <log expr="'Preparing to answer the call.'"/>
      <accept/>
    </transition>

    <transition event="connection.connected">
      <log expr="'Caller has connected.  Executing VoiceXML dialog now.'"/>
      <dialogstart src="'helloworld.vxml'" type="'application/voicexml+xml'" dialogid="myDialogID"/>
    </transition>

    <transition event="dialog.exit">
      <log expr="'The dialog is now complete.  Exiting application.'"/>
      <exit/>
    </transition>

    <transition event="error.*">
      <log expr="'An error has occured (' + event$.reason + ').  Exiting application.'"/>
      <exit/>
    </transition>

  </eventprocessor>
</ccxml>

This simple CCXML code snippet accept a user’s call, and launches a VoiceXML dialog titled helloworld.vxml. Now, all we need to do is modify the “src” attribute to reference the Designer application. How, you ask? Well, it’s a little tricky, but far from impossible. All we need to do is grab the Designer URL from the Application Debugger (or the Prophecy Log Viewer, for all the local installations out there). The full URLs will look something like this, and may require copying the link to the clipboard (in Evolution, at least) in order to see the entire thing:

Evolution Designer:

http://evodesigner-speech-dev.voxeo.com/SpeechRuntime/route.speech?vr.application.id=XXXX (where XXXX is your specific Application ID)

Prophecy Designer:

http://127.0.0.1:9992/SpeechRuntime/route.speech?vr.application.id=X (where X is your specific Application ID)

We can then inject this into the <dialogstart> keeping everything else the same. The dialog “type” remains “application/voicexml+xml” since Designer is pure VoiceXML behind the scenes, coupled with a custom GUI.

Now let’s take a look at the finalized code, with our Designer dialog in place.

<?xml version="1.0" encoding="UTF-8"?>
<ccxml version="1.0" xmlns:voxeo="http://community.voxeo.com/xmlns/ccxml">
  <var name="myDialogID"/>
  <eventprocessor>

    <transition event="connection.alerting">
      <log expr="'Preparing to answer the call.'"/>
      <accept/>
    </transition>

    <transition event="connection.connected">
      <log expr="'Caller has connected.  Executing Designer dialog now.'"/>
      <dialogstart  src="'http://127.0.0.1:9992/SpeechRuntime/route.speech?vr.application.id=4'"  type="'application/voicexml+xml'" dialogid="myDialogID"/>
    </transition>

    <transition event="dialog.exit">
      <log expr="'The dialog is now complete.  Exiting application.'"/>
      <exit/>
    </transition>

    <transition event="error.*">
      <log expr="'An error has occured (' + event$.reason + ').  Exiting application.'"/>
      <exit/>
    </transition>

  </eventprocessor>
</ccxml>

And there you have it — a basic application which launches a Designer dialog. Hopefully this will help shed some light on how developers can combine the utility of CCXML with the usability of Voxeo Designer.

Jeff Menkel VXML Certified Developer

Hi, I’m Dustin, and I’m a VoiceXML Certified Developer. This is the part where you all clap and welcome me and we spend the next hour talking about our feelings. Since this is my first blog on the interweb, I’ll spare you the pain this time and skip right to the meat and potatoes.

In this week’s Developer’s Corner blog, we’ll explore Answering Machine Detection – or Call Progress Analysis(CPA) if you wanna get technical. The kicker here is we’re not writing a complex CCXML to do it. In fact, we’re not going to write a single line of code today; we’re gonna whip it all up real quick and easy like in Designer – it’s Shake and Bake™, and you helped.

This blog assumes you have some working knowledge of the Designer tool. If not, check out our starter tutorial about Designer. This blog is geared towards our hosted platform; if you’re using a Premise installation of Prophecy, check out the bottom of this post where I’ve detailed the differences.

So what is CPA?

The Voxeo Call Progress Analyzer (CPA) offers customizable answering machine detection.  It uses advanced Digital Signal Processing (DSP) and voice activity detection to analyze the audio signal after a call is connected, making it possible to programmatically determine if the answering party is a human speaker, an answering machine, a modem or Cylon. Ok, so I made the Cylon part up…that part’s still in beta. Voxeo recently enabled Call Progress Analysis(CPA or Answering Machine Detection) on its shared hosting platform for Evolution Designer, so we figured we should probably let you know how to use it.

Creating our Project

If you’re not already logged into Evolution, go ahead and do so now. Click Evolution Designer and this should open a new window with the manage projects popup. Select Create a new project, New Project and click Next. Go ahead and enter a name and description for your project here and click Save. We don’t need the ‘Start’ step, so left-click on it and select Remove. This should bring us back to our call flow with only one step: Initial Step. Go ahead and click on this and click the blue plus sign at the bottom.

This will bring up the create step dialog. Let’s name this step CPA Result, because we’re creative like that, and select Decision as the type. Back at the call flow diagram now, we should see our new step. Go ahead and click on it and click Add. Let’s name our first rule Human. Click Browse and select CPA Result from the Data Variable pull down and click Ok. We’re checking to see if our string equals human, so go ahead and type human in the box next to the VC icon and click Add Condition. Under Select Destination click the blue plus and create a Prompt step and name it Human, click Save and then Ok. Repeat the rule creation process again, instead using machine instead of human. We’ll also need to create a ‘When No Rules Apply’ step, so click the blue plus one more time and create a Prompt step called Unknown. This is where our callee will be sent if CPA can’t figure out what they are. With all that completed, our step should now look like this:

All that’s left to do know is edit our Human, Machine and Unknown steps. We’ll need to add TTS for each open, so open them up and click New Audio. In my example, I simply put ‘CPA says you are a human/machine/etc’ and selected the Destination as the Hangup step. You, however, are free to get fancy here and create human and machine specific logic and input steps. Once we’re done here, all that’s left to do is click Publish and map our project up in Application Manager.

On our Evolution start page, click Application Manager then Add Application at the bottom. We should have a few options for application type here but we’ll want to select Evolution Designer and click Next. Now we’ll just need to fill in a name for our app, select it from the pulldown, click Create Application and we’re just about set. If you don’t already have an Evolution Designer token, you’ll want to grab one from the Voxeo support team. Open a new support ticket in your account from the Evolution home page or send an email to support@voxeo.com with your account name and the application you’d like the token for. Once we have this in hand, we can start launching outbound Designer calls by popping the URL below in our favorite browser and replace YOURPHONENUMBER with the number you wish to dial and YOURTOKENID with the token ID provided to you by the support team.

http://api.voxeo.net/SessionControl/VoiceXML.start ?numbertodial=YOURPHONENUMBER &tokenid=YOURTOKENID &voxeo-cpa-maxtime=4000 &voxeo-cpa-maxsilence=1000 &voxeo-cpa-runtime=20000

So what do these settings mean? I’ll steal some information directly from our docs to explain:

• voxeo-cpa-maxsilence The ‘cpa-maxsilence’ parameter is used to identify the end of voice activity.  When activity begins, CPA will measure the duration until a period of silence greater than the value of ‘cpa-maxsilence’ is detected.  Armed with start and end timestamps, CPA can then calculate the total duration of voice activity.  A value of 800 to 1200ms is suggested for this parameter.
• voxeo-cpa-maxtime The ‘cpa-maxtime’ parameter is the “measuring stick” used to determine ‘human’ or ‘machine’ events.  If the duration of voice activity is less than the value of ‘cpa-maxtime’, the called party is considered to be ‘human.’  If voice activity exceeds the ‘cpa-maxtime’ value, your application has likely called a ‘machine.’  The recommended value for this parameter is between 4000 and 6000ms.
• voxeo-cpa-runtime The ‘cpa-runtime’ parameter specifies the maximum amount of time CPA should listen for events.  If the ‘runtime’ exprires, CPA will return an “unknown” result.  Therefore, ‘cpa-runtime’ should always be longer than the average answering machine outgoing message.  We recommend a value of at least 15000-20000ms.

Possible CPA events:

These will be populated to the CPA Result variable within Designer as a string value.

• human
• machine
• beep
• modem
• faxtone
• sit

Enabling CPA for Prophecy Designer

Enabling CPA for Designer on a Premise installation of Prophecy is fairly simple. The wrapper that handles all the logic is already there, we just need to tell Designer to look out for CPA result. Assuming you installed Prophecy in the default path, open up C:\Program Files\Voxeo\Designer\config\GlobalVariables.conf. At the bottom of this file, paste in this line: voxeo_cpa_result=CPA Result

That’s it. Restart the Designer service by clicking the Prophecy tray icon and select Restart Services and Voxeo Prophecy Designer.

Publishing your project on a Premise installation

Once you’ve clicked Publish on your completed Designer project, return to Management Console(Prophecy tray icon > Prophecy home > Management Console) and select the Call Routing menu option. Scroll down until you find the route named Designer. Click the App Name drop down and select your project. Verify App Version is set to Latest and then scroll to the bottom of the page and click Save Changes. To test our new outbound application, open the Prophecy SIP phone(Prophecy tray icon > SIP Phone), open up your web browser and paste in this URL:

http://127.0.0.1:9998/VoiceXML.start ?numbertodial=sip:user@127.0.0.0.1:5070 &tokenid=designer &voxeo-cpa-maxtime=4000 &voxeo-cpa-maxsilence=1000 &voxeo-cpa-runtime=20000