CallXML 2.0 Development Guide

| TOC

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Answering Machine Detection

The Voxeo Call Progress Analyzer (or 'CPA' for those into brevity) 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 even a fax.

Note that since there are absolutely no standards at all for answering machine beeps, and every machine is different, there is no guaranteed solution that will detect a machine pickup 100% of the time. But with enough tweaking of the CPA values, it is possible to detect this most of the time. Also be aware that detection of a 'beep' event is notoriously harder to detect than a 'machine' result, so it is always best to trap both events in your code.

Reminder: Outbound dialing requires the use of outbound dialing priveleges, which must be provisioned by voxeo support. If you have not contacted us to get these permissions, click here to learn how you can get hooked up with this feature.

Call Progress Analyzer Parameters

voxeo-cpa-version
This parameter is optional. The current CPA version is "2.0."

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.

voxeo-cpa-maskevent
The 'cpa-maskevent' parameter lists the CPA results that should throw an event. This assures that only desired results, important to your specific application, will be acknowledged. The value for this parameter should be a comma-separated list, any combination of the following:

human
machine
beep
modem
faxtone
*sit

* For those who are aspiring telephony geeks, SIT stands for "Special Information Tones." These are the tones you might hear when calling a disconnected or not in-service number.

voxeo-cpa-maskstop
The 'cpa-maskstop' parameter lists the CPA results that, when received, will simply stop CPA from listening for further events. The value for this parameter should be a comma-separated list, any combination of the following:

human
machine
beep
modem
faxtone
sit

Call Progress Analyzer Results

human
A 'human' result is determined when the duration of initial voice activity is less than the 'cpa-maxtime' value.

machine
A 'machine' result is determined when the duration of initial voice activity is greater than the 'cpa-maxtime' value.

beep
A 'beep' result indicates that CPA's Digital Signal Processing (DSP) has encountered a pure tone.

modem
CPA has detected a modem.

faxtone
CPA has detected a fax machine.

SIT
A 'SIT' result indicates that CPA detected Special Information Tones - SIT tones. This generally means that the called number has been disconnected or is no longer in service.

unknown
An 'unknown' result is returned when the 'cpa-runtime' expires.

Simple CPA Example Code

The below example illustrates basic usage of CPA at its most simplistic. The application will be initiated using a tokenID, create an outbound call, and simply log the CPA result value. Use this application to familiarize yourself with CPA’s detection algorithm as described above.

SimpleCPA.xml



<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">



  <call value="tel:1112223333"

        maxtime="60"

        voxeo-cpa-maxsilence="1"

        voxeo-cpa-maxtime="4"

        voxeo-cpa-runtime="20"

        voxeo-cpa-maskstop="human, machine, beep"

        voxeo-cpa-maskevent="human, machine, beep"/>



 <onanswer next="#waitBlock">

   <log value="*** Call has been answered ***" />

 </onanswer>



<block label="waitBlock">

  <wait value="60"/>

  <exit/>

</block>



<oncparesult type="human">

  <log value="*** HUMAN DETECTED ***"/>

  <exit/>

</oncparesult>



<oncparesult type="machine">

  <log value="*** MACHINE DETECTED ***"/>

  <exit/>

</oncparesult>



<oncparesult type="beep">

  <log value="*** BEEP DETECTED ***"/>

  <exit/>

</oncparesult>



<oncparesult type="unknown">

  <log value="*** CPA RUNTIME EXPIIRED ***"/>

  <exit/>

</oncparesult>



<onerror>

  <log value="*** $session.lasterror; ***"/>

  <text>

    A naughty error has occured.

    This application will now gracefully bow out.

  </text>

</onerror>



</callxml>

Advanced CPA Example Code

Most real-world applications will likely block a bit more than simply log a CPA event, and exit. More often than not, you will need to play a message or invoke a VoiceXML dialog based on the CPA result.

The below sample script shows how we can tweak the CPA parameters and add clever application logic to suit our specific needs. This particular application is designed to leave a full and complete message ('message.wav') with either a human recipient or an answering machine. You will notice that we are now incorporating several bits of logic around our CPA usage to achieve this goal:

We list our desired events – human, machine, beep – in our 'maskevent.'
The 'maskstop' is left empty. This allows CPA to listen for multiple events (e.g. "machine" --> "beep")
We increase the 'runtime' to a duration that is longer than the anticipated length of the call. We block this because we block not want the CPA event "unknown" to fire and interrupt our message.
To assure that the full message is delivered, we simply restart the message dialog if a new CPA result is received.

AdvancedCPA.xml



<?xml version="1.0" encoding="UTF-8"?>

<callxml version="2.0">



  <call value="tel:1112223333"

        maxtime="60"

        voxeo-cpa-maxsilence="1"

        voxeo-cpa-maxtime="4"

        voxeo-cpa-runtime="300"

        voxeo-cpa-maskstop=""

        voxeo-cpa-maskevent="machine, beep"/>



<onanswer next="#waitBlock">

   <log value="*** Call has been answered ***" />

</onanswer>



<block label="waitBlock">

  <wait value="60"/>

  <exit/>

</block>



<block label="playMessage" repeat="2" next="#messageComplete">

  <playaudio value="message.wav"/>

</block>



<block label="messageComplete">

  <log value="*** MESSAGE COMPLETE / EXIT ***"/>

  <exit/>

</block>



<oncparesult type="human" next="#playMessage">

  <log value="*** HUMAN DETECTED ***"/>

</oncparesult>



<oncparesult type="machine" next="#playMessage">

  <log value="*** MACHINE DETECTED ***"/>

</oncparesult>



<oncparesult type="beep" next="#playMessage">

  <log value="*** BEEP DETECTED ***"/>

</oncparesult>



<oncparesult type="unknown">

  <log value="*** CPA RUNTIME EXPIIRED ***"/>

  <exit/>

</oncparesult>



<onerror>

  <log value="*** $session.lasterror; ***"/>

  <text>

    A naughty error has occured.

    This application will now gracefully bow out.

  </text>

</onerror>



</callxml>

ANNOTATIONS: EXISTING POSTS

grevs

4/8/2005 1:16 PM (EDT)

The cpa values seem really low for the .php example

I was only able to achieve success in this example by using the suggested values from earlier in the example:

<call value="14165551212"
voxeo-cpa-version="2.0"
voxeo-cpa-runtime="15000ms"
voxeo-cpa-maxtime="5000ms"
voxeo-cpa-maxsilence="1200ms"
voxeo-cpa-maskevent="human,machine,beep,faxtone"
voxeo-cpa-maskstop="human,machine,beep,faxtone"
/>

Michael.Book

4/8/2005 1:52 PM (EDT)

Howdy "grevs,"

My apologies for the confusion. This is simply a typo that will be fixed as quickly as possible. The values should actually read something like:

voxeo-cpa-runtime="15000ms"
voxeo-cpa-maxtime="4000ms"
voxeo-cpa-maxsilence="1200ms"

Although, I personally use the following values for my CPA enabled applications:

voxeo-cpa-runtime="20000ms"
voxeo-cpa-maxtime="4000ms"
voxeo-cpa-maxsilence="1000ms"

Cheers,

~ Michael

telnform_prod

4/7/2006 1:54 AM (EDT)

oncparesult tags are missing the type property
example: <oncparesult type="human"/>

This may be something that is different depending on specific circumstances, but it was causing errors for me.

Also <onanswer> should have a next=""...I know it's just a sample, but it's nice to just copy, paste and test.

And "human" is missing from mask-event (following the text description above)

mikethompson

4/7/2006 11:28 AM (EDT)

Hey there,

Thanks for pointing out the issue. I have notified the keepers of the documentation and it has been placed in their queue to be corrected.

Thanks again,
Mike Thompson
Voxeo Extreme Support

Token Initiated Calls

| TOC

| ANI and DNIS