VoiceXML 2.1 Development Guide

Home | Frameset Home

Call Transfer

| TOC

DTMF Recognition

Tutorial: Called ID and Caller ID

This tutorial is based on the things you accomplished in tutorials 1 through 3. If you have not completed those yet, you'll need to go through them first.

Step 1: Creating our initial VoiceXML structure

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


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

</vxml>

Step 2: Some words about Caller ID and Called ID

You visited the use of VoiceXML variables in Tutorial 4, when learning how to send the call flow to a different web page. All that is needed to get the ANI and DNIS is to access either the 'session.callerid' or 'session.calledid' variable (depending on your needs).

Ummm, what does "ANI" and "DNIS" mean?

These are standard telephony industry terms, but they are more commonly known as "Caller ID" and "Called ID". Caller ID/ANI is the ten digit phone number of the telephone that initiated the call in the first place. Most people are familiar with this. But "Called ID/DNIS" is the telephone number being called; thus, if your mother's phone number was "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.telephone.dnis would be 8005551234, right?

Not exactly. The 'session.calledid' value reflects 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. These variables are persistent as VoiceXML variables through the session. You do not have to explicitly state that they should be passed, they are always there; so you cannot prevent them from showing up in your code. However, this is only true for the VoiceXML variable space. If you are using a backend/server-side scripting language (such as PHP, ASP, Allaire's ColdFusion, Perl, JSP, etc.), these variables are passed via the HTTP GET methodology into the first page (and only the first page). If you want to preserve those variables as HTTP GET variables, you will have to pass them manually.

You should also be aware that due to the system architecture, 'session.callerid' and 'session.calledid' will not be displayed when using the 800/407 + PIN system, but they will show up correctly when using a direct dial, (i.e. no PIN code), 407 number.

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

<vxml version = "2.1">

  <form id="Hello_World">
    <block>
     <prompt>
      Hello there. The caller i d number is <value expr="session.callerid"/>
      The called i d of this application is <value expr="session.calledid"/>
    </prompt>
   </block>
  </form>
</vxml>

Yep, it is just that simple. Of course, there is a humorous caveat to this code. When you upload this code, it will read the caller and called ids as actual numerical values. Thus, 8005551234 will come across as 8,005,551,234 (or eight billion, five million, five hundred fifty one thousand, two hundred thirty four). To read numbers on a digit-by-digit basis, you would have to add the following SSML 'tweaks' to the code:


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

  <form id="Hello_World">
    <block>
     <prompt>
      Hello there. The caller i d number is: 
       <say-as interpret-as="telephone">
            <value expr="session.callerid"/>
        </say-as>
      The called i d of this application is: 
        <say-as interpret-as="telephone">
          <value expr="session.calledid"/>
        </say-as>
      </prompt>
    </block>
  </form>
</vxml>

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 VoiceXML 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.)

Download the Code!

Source Code

What was just covered:

Revisited VoiceXML variables
Learned how to access the session.callerid and session.calledid variables
Learned basic SSML TTS formatting by way of the <say-as> element

ANNOTATIONS: EXISTING POSTS

davidt

2/2/2007 2:09 AM (EST)

When I use interpret-as="telephone", the number is still read as "eight billion, five million, ...". I'm guessing the "telephone" option only works when the number is correctly hyphenated as in "800-555-1234," but session.callerid and session.calledid lack hyphens.

To get the number read as a string of digits, I used <say-as interpret-as="number" format="digits">.

mikethompson

2/2/2007 9:33 AM (EST)

Hi David,

If you take a look at the annotations at the bottom of the <say-as> element documentation, I think you will find what you're looking for. Allow me to show you a post which demonstrates your issue:

=======================
Another note:

If you use
<say-as interpret-as="telephone">3125551212</say-as>

you'll get

"three billion one hundred twenty-five million five hundred fifty-one thousand two hundred twelve"

If you use
<say-as interpret-as="phone">3125551212</say-as> as per the VoiceXML 2.0 spec appendix P, you'll get

"three one two five five five one two one two", but without any pauses between digit groups (area code, exchange, number).
=========================

Also note this response by Matt Henry:

==========================

Per the rVoice manual, (available upon request), the say-as type for this should indeed be set as type="telephone", but note that it does expect dashes in the string for it to be rendered properly:

"1112223333" versus "111-222-3333"

==========================

For further posts and great documentation, you can go here:
http://docs.voxeo.com/voicexml/2.0/say-as.htm

Regardless, based on the calledID and callerID tutorial, it looks like you don't need to add dashes to have the string read correctly.

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

<form id="Hello_World">
<block>
<prompt>
Hello there. The caller i d number is:
<say-as interpret-as="telephone">
<value expr="session.callerid"/>
</say-as>
The called i d of this application is:
<say-as interpret-as="telephone">
<value expr="session.calledid"/>
</say-as>
</prompt>
</block>
</form>
</vxml>

This may be related to a difference in Rhetorical TTS vs. Speechify TTS. We'll run a few tests in our labs here and see what's going on.

Best,
Mike Thompson
Voxeo Corporation

voxeojeff

2/2/2007 2:30 PM (EST)

Hi David,

After some testing, Mike's code snippet seems to work just fine. Using the session.callerid and session.calledid values inside of the <say-as interpret-as="telephone"> tag, it should read out the number correctly. For example, in my test case...

Logs:
VEC::getCallingNumber(): Calling Number is [4074181800]
VEC::getCalledNumber(): Called Number is [3212022485]

The numbers are read out as 'four zero seven four one eight one eight zero zero' and 'three two one two zero two two four eight five.' So, hyphens are not needed to have the string read out as it should. :-)

Best,

Jeff Menkel
Voxeo Corporation

atalapan

7/10/2007 6:57 AM (EDT)

How does Called ID work with toll-free numbers? Say you have both 1800-123-4567 and 1-866-222-1234 that both point to 123-234-4567. When you inquire about the Called ID, do you get the toll-free number that the user called, or do you get the underlying number that the toll-free number points to (123-234-4567)?

VoxeoDante

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

Hello Atalapan,

If you have the number 1-866-222-1234 which points to 123-234-4567, when the originating number (1-866-222-1234) is dialed, this will be the calledid for that particular session.

Same as if the other number 1800-123-4567 is dialed, this will become the calledid of the particular session.

The calledid is assigned when the call is placed, not when the application is hit. The calledid is a value which is passed to the voice platform my the Telco.

I hope this answers your question. If not, please let us know.

All the Best,
Dante Vitulano
Voxeo Extreme Support

Denell

12/26/2007 6:50 PM (EST)

response to VOXEOJEFF

When running the trace I get

00020 ade5 VEC::getCallingNumber(): 408xxxxxxx
00021 ade5 VEC::getCalledNumber(): 4155039823

but on the phone I do not get your results. The number is still read as 4 billion.......not digit by digit.

I opened up a support ticket info below

Account Ticket #512270:

Thanks,
Denell

VoxeoTony

12/26/2007 8:50 PM (EST)

Hello Denell,

We received the account ticket you created to follow up on your questions. At this time, we'll continue the focused troubleshooting efforts in that ticket with you.

Regards,

Tony

jpw

1/13/2008 8:45 PM (EST)

using evolution designer hosted at Voxeo (and a inbound Seattle number provided via your voxeo network) to access the xml file on my own server, the interpret-as="telephone" is definitely reading the caller ID as billions and millions and thousands etc -- NOT as a phone number.

voxeojeff

1/14/2008 11:18 AM (EST)

Hello,

This was a bug in Prophecy 7, where say-as interpret-as="telephone" would only work when the number to be read back was hyphenated. This has been corrected in Prophecy 8, which is not currently available in our hosted environment, but will be soon (no hard ETA yet). If you would like to test this, you can download a local version of Prophecy 8, which contains the fix for this, at www.voxeo.com/prophecy.

Hope this helps,

Jeff

theuntested

7/18/2008 4:54 PM (EDT)

Can you show an example of how to answer the call with specific TTS depending on which number the caller dialed to access the application.
I have two numbers pointing to the same app and would like to answer differently depending on which number the called dialed.

voxeojeff

7/18/2008 5:19 PM (EDT)

Hello,

It almost sounds like you want to create a multi-lingual application. I.e., if a user calls in via phone number A, then launch the English version, and B would be for Spanish (for example). If this is true, then you can split your application up into forms, and use conditional logic coupled with the <goto> element in order to navigate the application. For example, lets say 4071112233 is the number which is supposed to point to Spanish:
[code]
<form id="Intro">
<block>
<if cond="session.calledid == '4071112233'">
<goto next="#Spanish"/>
<else/>
<goto next="#English"/>
</if>
</block>
</form>

<form id="Spanish">
<block>
<prompt xml:lang="es-mx-fm3">
Hola! como estas?
</prompt>
</block>
</form>
[/code]

I hope this helps clarify how you can accomplish this. Please let me know if you have any questions.

Thanks,

Jeff

Call Transfer

| TOC

DTMF Recognition