CallXML 3.0 Development Guide

| TOC

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. Also, if you would like a list of the available web services, go to B: Outbound Dialing.

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="3.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"/>



 <on event="answer" next="#waitBlock">

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

 </on>



<block label="waitBlock">

  <wait value="60"/>

  <exit/>

</block>



<on event="cparesult:human">

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

  <exit/>

</on>



<on event="cparesult:machine">

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

  <exit/>

</on>



<on event="cparesult:beep">

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

  <exit/>

</on>



<on event="cparesult:unknown">

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

  <exit/>

</on>



<on event="error">

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

  <say>

    A naughty error has occured.

    This application will now gracefully bow out.

  </say>

</on>



</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="3.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"/>



<on event="answer" next="#waitBlock">

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

</on>



<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>



<on event="cparesult:human" next="#playMessage">

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

</on>



<on event="cparesult:machine" next="#playMessage">

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

</on>



<on event="cparesult:beep" next="#playMessage">

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

</on>



<on event="cparesult:unknown">

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

  <exit/>

</on>



<on event="error">

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

  <say>

    A naughty error has occured.

    This application will now gracefully bow out.

  </say>

</on>



</callxml>

ANNOTATIONS: EXISTING POSTS

jagpno

1/14/2007 2:36 PM (EST)

Neither example works with Prophecy version 7.0.242.0, but returns an error: unhandled event "event="oncparesult", id="", type="human"

There are also a couple of typos:
<callxml version="2.0">

Should be:
<callxml version="3.0">

Advanced CPA reads:
<on event="error>

Should be:
<on event="error">

But even after fixing these, it still does not work.

MattHenry

1/14/2007 5:53 PM (EST)

Hi there,

Per the engineering team, it appears as if we recently introduced a system bug where the presence of the <exit/> tag in the block prevents events from being fired correctly while in this block. We have sceduled some engineering face-time with this bug on Monday where we can look at applying a patch for this problem, but in the meantime, we can replace <exit/> with a <goto> that points to a to a block that contains the exit tag.

Let me know if this presents any difficulties!

~Matthew Henry

MattHenry

1/24/2007 6:26 PM (EST)

Just as an FYI, this has been fixed in prophecy build 286+. We expect to have a GA release ready within the next few days that will allow you to run the code as presented in the documentation.

Cheers,

~Matthew Henry

giridhar

7/23/2007 10:59 AM (EDT)

in case of an error or MACHINE DETECTED how do i update my database ? or send a message to my web server ? using callxml ?

VoxeoBrian

7/23/2007 1:59 PM (EDT)

Hello,

Within CallXML, to submit the status of a call back to a webserver simply utilize the on event to capture any given event. Then, use goto with the submit attribute to store that in your DMBS.

Here is an example for a CPA human event:
<on event ="cparesult:human">

On Event
http://docs.voxeo.com/callxml/3.0/on.htm

Goto

http://docs.voxeo.com/callxml/3.0/goto.htm

Please let me know if this helps to clarify this for you, as well if you have any additional questions we are standing by to assist.

Regards

Brian

jpw

2/18/2008 4:48 PM (EST)

someone was editing and did a global search/replace in several places where do -> block, eg see "Most real-world applications will likely [b]block[/b] a bit more"

jpw

2/18/2008 5:29 PM (EST)

In the 'advanced' example I think you forgot to add "human" to the maskevent

VoxeoDustin

2/18/2008 6:57 PM (EST)

Hey JP,

Thanks for the heads-up. I have forwarded this off to our doc maintainers and it should be corrected in the next build of the docs.

Thanks,
Dustin

Deke

2/19/2010 9:31 AM (EST)

In the advanced call process analyzer example, you handle the 'unknown' event even though that isn't a maskevent. Is that a mistake or does it really need to be handled?

Also, this is somewhat minor, but I found this sentence:

We block this because we block not want the CPA event "unknown"
to fire and interrupt our message.

...I block not like it when people global replace 'do' with 'block'. ;)

VoxeoDante

2/19/2010 1:01 PM (EST)

Hello Deke,

The CPA unknown event is thrown when the 'cpa-runtime' expires. It is recommended that you handle this event so that the application is aware if there have not been any CPA events thrown during the time specified.

Also thanks for finding that error in the documentation. It looks like we may have done a find and replace on do and removed some things we should not have.

I am going to forward this to the Documentation team and ask them to make the update.

Regards,
Dante Vitulano
Customer Support Engineer II
Voxeo Corporation

CHardin

5/21/2010 10:30 AM (EDT)

To use the sit event do I use

<on event="cparesult:*sit">
<log value="*** Disconnected Number ***"/>
<sendemail from="CallXML@MyIVR.com" to="Me@MyIVR.com">
$NumToCall; has been disconnected.
</sendemail>
<exit/>
</on>

or

<on event="cparesult:sit">
<log value="*** Disconnected Number ***"/>
<sendemail from="CallXML@MyIVR.com" to="Me@MyIVR.com">
$NumToCall; has been disconnected.
</sendemail>
<exit/>
</on>

VoxeoDante

5/22/2010 12:11 AM (EDT)

Hello,

It should be the latter, I am not sure where the *sit came from.

[code]<on event="cparesult:sit">
<log value="*** Disconnected Number ***"/>
<sendemail from="CallXML@MyIVR.com" to="Me@MyIVR.com">
$NumToCall; has been disconnected.
</sendemail>
<exit/>
</on> [/code]

Please let us know if you see any results that do not match this.

Regards,
Dante Vitulano
Customer Obsession Team
Voxeo Corp.

Token Initiated Calls

| TOC

| CallerID, ANI and DNIS