Customizing Voice Broadcast

Introduction

A common use of Voice XML is customizing a voice message based on the phone number being called. CallFire's VoiceXML platform provides applications with pre-populated session variables that can be used by application developers as a key to look up information in their own data stores.

<?xml version="1.0" encoding="UTF-8"?> 
<!-- -*-SGML-*- -->
<vxml version = "2.1"
      xmlns="http://www.w3.org/2001/vxml">
<form>
  <property name="interdigittimeout" value="0s"/>
  <!-- The caller ID of the number being called -->  
  <var name="telephone" expr="session.telephone.ani"/>
  <!-- The internal CallFire call ID of the call -->
  <var name="callid" expr="session.telephone.dnis"/>
  <block>
   <prompt>
      Your number is
    </prompt>
    <value expr="ani"/> .
    <submit next="http://your.company.com/vxmlserver" method="post" namelist="callid telephone"/>
  </block>

</form>
</vxml>

This example shows how to use the session.telephone.ani and the session.telephone.dnis variables to get more information about the call. Once the value of these variables are captured, the programmer can write code that can dynamically determine the call flow.

The URL in the next attribute of the submit tag should return a valid document. This is where the power of VXML becomes clear. The URL could be a PHP script, a Java or C# server that returns the Voice XML document. The use case in the next section gives one possible implementation.

Use Case: Customized Weather Forecast

If, for example, you wanted to give your customers personalized weather broadcast.

Sample Call Flow

The vxml document for such a call flow will look like:

<?xml version="1.0" encoding="UTF-8"?>
<!-- -*-SGML-*- -->
<vxml version = "2.1"
      xmlns="http://www.w3.org/2001/vxml">
<form id="top">
    <block>
     <prompt>Hello John Doe, the weather forecast for your area is mostly sunny
 with ten percent chance of rain. Thank you for subscribing to our service.
     </prompt>
    </block>
</form>
</vxml>

Algorithm

Regardless of technology platform, a programmer can see there are at least two points of personalization in this script. The first, of course, is the name of the callee and the second is the weather in their area. The algoritihim is going to be a four step process:

1. Get HTTP Parameters: The parameters (the CallFire call id and the telephone number) need to be unmarshalled from the HTTP request.
2. Query Local Database: In most systems the telephone number can be considered as a key. Use the telephone number to query the database and get the name and weather.
3. Create VXML Document: With all the dynamic data queried, now create a well-formed, valid VXML document.
4. Return VXML Document: As mentioned, the submit directive expects a well-formed VXML document as response. Return the VXML document from step 3 as part of the HTTP response.

Sample Code: Java

import java.io.IOException;
import java.io.PrintWriter;

import javax.servlet.ServletException;
import javax.servlet.http.HttpServlet;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

public class VXMLServer extends HttpServlet 
{
	/**
	 * The doPost method of the servlet. <br>
	 *
	 * This method is called when a form has its tag value method equals to post.
	 * 
	 * @param request the request send by the client to the server
	 * @param response the response send by the server to the client
	 * @throws ServletException if an error occurred
	 * @throws IOException if an error occurred
	 */
	public void doPost(HttpServletRequest request, HttpServletResponse response)  throws ServletException, IOException 
	{
                //Step 1: Unmarshall the HTTP Paramaters
		String callid = request.getParameter( "callid" );
		String telephone = request.getParameter( "telephone" );
		response.setContentType("text");
		PrintWriter out = response.getWriter();
                //Step 2 & 3
                String emptyDocument = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>" +
			            "<vxml version=\"2.1\">" +
			            "<form><block><prompt>" +
			            " Hello " + yourBusinessObject.getName(telephone) + 
                                    " the weather forecast for your area is " +
                                     yourBusinessObject.getWeather(telephone) +
                                    "Thank you for subscribing to our service." +
			            " </prompt></block></form>" +
			            "</vxml>";
                //Step 4
		out.println( emptyDocument );
		out.flush();
		out.close();
	}
}

Here yourBusinessObject, as the the name suggests, is your customer business object and can be as simple or complex as your business model