Voice XML Answering Machine Detection

Introduction

This document shows how to leverage the CallPeer service's createVxmlCampaignObject operation to create Voice XML campaigns that detect live answers and answering machines.

How it Works

The calling system will try and detect if the phone has been answered by a person or an answering machine and will transfer control to the appropriate Voice XML script.

Overview

The crux of the operation is the VxmlCampaignObject complex type

<xsd:complexType name="VxmlCampaignObject">
 <xsd:sequence>
  <!-- The URL for the Voice XML script that will be called when an Answering Machine is detected -->
  <xsd:element minOccurs="0" name="amUrl" nillable="true" type="xsd:string"/>
  <!-- The caller id of the Campaign -->
  <xsd:element minOccurs="0" name="callerid" nillable="true" type="xsd:string"/>
  <!-- If this flag is set to true, the AM URL validated, else ignored -->
  <xsd:element minOccurs="0" name="enableAM" type="xsd:boolean"/>
  <!-- The API Key -->
  <xsd:element minOccurs="0" name="key" nillable="true" type="xsd:string"/>
  <!-- The URL for the Voice XML script that will be called when a live person answers -->
  <xsd:element minOccurs="0" name="laUrl" nillable="true" type="xsd:string"/>
  <!-- The array of phone numbers -->
  <xsd:element minOccurs="0" name="numbers" nillable="true" type="tns:ArrayOfString"/>
 </xsd:sequence>
</xsd:complexType>

This campaign object simplifies the call where in all the information is sent in as one object. This is especially helpful for web services calls from generated clients.

Example

The best way to show this new operation in action is to show it via source code. Here's an example in Java using the industry standard Java-WS web services client.

package com.callfire;
/**
 * @author jthinaka
 * @author techsupport@callfire.com
 * @version 0.1 alpha
 * @description Test client to show Voice XML AMD Detection SOAP calls
 */
public class VxmlServiceTest 
{

	/**
	 * @param args
	 */
	public static void main(String[] args) 
	{
		// Instantiate the generated Object Factory
		ObjectFactory of = new ObjectFactory();
		
		// Instantiate the (generated) service client and get the http port
		CallPeer service = new CallPeer();
		CallPeerPortType portType = service.getCallPeerHttpPort();
		
		/*
		 *  Add numbers. This can be put inside a loop that populatest the array from
		 *  your data source
		 */
		ArrayOfString aoString = of.createArrayOfString();
		aoString.getString().add("2135552586");
		
		/*
		 * This is the main object.
		 */
		VxmlCampaignObject vxmlObject = new VxmlCampaignObject();
		vxmlObject.setEnableAM(true);  // Setting it to true enables AMD
		vxmlObject.setAmUrl( of.createVxmlCampaignObjectAmUrl( "<YourURL>" ) );
		vxmlObject.setCallerid( of.createVxmlCampaignObjectCallerid("7855555555") );
		vxmlObject.setLaUrl( of.createVxmlCampaignObjectLaUrl("<YourUrl>"));
		vxmlObject.setNumbers( of.createVxmlCampaignObjectNumbers( aoString ) );
		vxmlObject.setKey( of.createVxmlCampaignObjectKey("<YourKey>") );
		
		// The one-line web service call.
		long campaignID = portType.createVXMLCampaignObject( vxmlObject );
		
		// Check and see if it went through. 
		// As is with any CallFire call, if the value is negative 
		// something went wrong. 
		if ( campaignID > 0 )
		{
			System.out.println( " Campaign created with id " + campaignID );
		}
		else
		{
			System.out.println( "There was an error" );
		}
	}
}