Tutorial: Hello World with caller ID and called ID

This Lesson is based on the things you accomplished in Lessons1, 2, and 3. If you have not completed these yet, you'll need to go through them first.

In this Lesson, you will:

Learn how to identify the Caller ID
Learn how to identify the Called ID
Learn how to read numbers over the phone
Upload the new "Hello World" application, and try it out

Step 1: Creating our initial callxml structure

From the previous tutorials, you now recognize the following structure as a normal starting point:


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

  <do>
  </do>

</callxml>

Step 2: Some words about Caller ID and Called ID

Most people are familiar with Caller ID, which is the ten digit phone number of the telephone that initiated the call in the first place. But "Called ID" is the telephone number being called; thus, if your mother's phone number is "1-800-555-1234", and your application called her number (the so called "Mom-O-Matic Autodialer" application that has taken Europe by storm), then the session.calledid would be 8005551234, right?

Not exactly. The session.calledid is the provisioned telephone number of the application in question. It is identical to the telephone number listed under your user account on the community portal. So another way to think of session.calledid is as the "application number". It points not to your mother's phone number, but the "Mom-o-matic autodialer" application itself. Like all session variables in callxml, these are continuously passed along the querystring each time a <goto> or a <run> is parsed. You do not have to explicitly state that they should be passed. They are always passed, so you cannot prevent them from showing up in your code.

One last thing to note about session variables: they are all read only. So it comes as no shock that the 'session.callerid' and 'session.calledid' variables cannot be altered inside CallXML.

Step 3: The code

This very basic code snippet demonstrates that the numbers are, in fact, being passed into your application. What you do with them afterward is up to you.


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

  <do repeat="3">
    <say>Hello there. The caller i d number is:</say>
    <log>*** SESSION.CALLERID = $session.callerid;***</log>
    <playnumber value="$session.callerid;" format="digits"/>

    <say>The called i d of this application is:</say>
    <log>*** SESSION.CALLEDID = $session.calledid ***</log>
    <playnumber value="$session.calledid;" format="digits"/>

    <wait value="3s"/>
  </do>

  <on event="error">        
   <sendemail from="MyApp@here.com" 
    to="YourEmail@there.net" type="debug"> 
    We caught an error in our application.  Details follow... 
   </sendemail> 
  </on> 

</callxml>

Yep, it is just that simple. Of course, there is a CallXML tag here that we have not covered before. <playnumber> is very similar to the callxml <say> tag, except that it will read a number to you instead of text. You use the "format" attribute to switch between reading individual digits, one at a time, and the entire number as if it were a mathematical expression. (i.e., You wanted it to read the number "12345" as " 1 2 3 4 5" not as "12,345". But if you wanted it to read using the latter method, simply change the code ........)


    <playnumber value="12345" format="number"/>

A last point of clarification before we are finished involves the <wait> element. As you might remember, this is simply a pausing feature that, in this case, pauses for 3 seconds. This way we can loop through our block, but have a more natural pause before repeating the information. The <wait> tag may also contain a "choices" attribute so that it can get interrupted:


    <wait value="3s" choices="12#*"/>

Step 4: Upload, and try it out

Your "Hello World" with Caller ID and Called ID is now done. Call the number associated with your callxml application, and you'll find that the results of this tutorial work just like the previous one. Except now, we know who is calling and what is being called.

CallXML 3.0 source code.

What was just covered

Delved deeper into callxml session variables
Learned how to access the session.callerid and session.calledid variables
Further explored the wait element
Learned about the <playnumber> element

ANNOTATIONS: EXISTING POSTS

hugob

8/29/2008 4:07 AM (EDT)

Hi.
Just a comment on the 'choices' attribute of the <wait> tag: shouldn't the options be comma seperated? That is,
<wait value="3s" choices="1,2,#,*"/>

voxeoJeffK

8/29/2008 4:50 AM (EDT)

Hi,

Good catch. We'll update the master docs, and the change should go live soon.

Thanks,
Jeff K.

Introduction to CallerID

| TOC

| Introduction to Call Bridging