CallXML 2.0 Development Guide

| TOC

This documentation is for CallXML 2, which has been superceded by CallXML 3. The CallXML 2 language is not being updated any longer. CallXML 3, however, has many new features and is actively being enhanced. If you're writing a new CallXML application, you should use CallXML 3. Click here for the CallXML 3.0 documentation.

Tutorial: Hello World with call bridging

This Lesson is based on the things you accomplished in lessons 1, 2, and 3. If you have not yet done those tutorials, you'll need to go through them first.

Note: This tutorial 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.

In this Lesson, we will:

learn how to initiate a new session
place an outbound call from that session
send an external event from one session to another
conference two calls together
upload the new hello world app and try it out

Step 1: creating our initial callxml structure

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



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

<callxml version="2.0">



  <block>

  </block>



</callxml>

Step 2: preparing to spawn a new session

In order to initiate a new session, place an outbound call, and tell our first session about the status of that call, we will need to assign at least one variable. Use the session.id variable to hold the current session's identifier -- since the new session we are about to create will have its own unique id, we need to store the current session's id, and pass that variable along to the new session.

We will also pass a variable called: NumToCall; this is the phone number we are ultimately going to call.



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

<callxml version="2.0">



  <block>

     <assign var="ParentSessionID" value="$session.ID;"/>

    <assign var="NumToCall" value="18005551234"/>



  </block>



</callxml>

To actually create the new session, we use the *run element. This element will run/start a new session, and fetches a CallXML document to use for the session from the URL or URI specified by value. Like the goto element, we have a destination file: run value="newCall.xml", a variable sequence to pass: submit="*", and the http method of sending that variable sequence: method="get"; however, we also have an attribute called var which stores the session.id of the NEW session: var="NewSessionID". Note that var is not the name of the new session, it is the name of the variable that holds the id of the new session. Tricky, right? Let's take a look and see:



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

<callxml version="2.0">



  <block>

    <assign var="ParentSessionID" value="$session.ID;"/>

    <assign var="NumToCall" value="18005551234"/>



    <run value="newCall.xml" submit="*" method="get" var="NewSessionID" />



    <wait value="10s"/>

  </block>



</callxml>

So why do we need to have a variable that holds the new session's id? If you need to send an event from the current session to the new session, you simply use the variable (in this case, the one named: NewSessionID). In our example, we will be sending events in the opposite direction though; that is, from the new session to the old session (which is why we created the variable named: ParentSessionID).

Perhaps most importantly, is that the current xml file will continue to parse after we hit the 'run' statement (unlike: goto which will jump to the specified label). So, if we want to place an outbound call in the new session, we have to play hold music or somehow wait for the call to go through in the current session. After recording some appropriate hold music, your code might look something like this:



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

<callxml version="2.0">



  <block>

    <assign var="ParentSessionID" value="$session.ID;"/>

    <assign var="NumToCall" value="18005551234"/>



    <run value="newCall.xml" submit="*" method="get" var="NewSessionID" />



    <wait value="10s"/>

     <block label="HoldMusic"

           repeat="3">



       <playaudio format="audio/wav"

           value="HoldMusic.wav"

           termdigits=""/>



      </block>



  </block>



</callxml>

Step 3: adding our event handlers

We need to add our onExternalEvent handlers. Since we have not looked at the XML file we called with our 'run' command, these events may still look unfamiliar; however, the most important "tidbit" to remember is that the value of an external event is user-defined. You can send any string or value between sessions...



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

<callxml version="2.0">



  <block>

    <assign var="ParentSessionID" value="$session.ID;"/>

    <assign var="NumToCall" value="18005551234"/>



    <run value="newCall.xml" submit="*" method="get" var="NewSessionID" />



    <block label="HoldMusic"

           repeat="3">



       <playaudio format="audio/wav"

           value="HoldMusic.wav"

           termdigits=""/>



      <onexternalevent value="Success">

        <conference targetsessions="$session.EventsenderID;"/>

        <hangup/>

      </onexternalevent>





       <onexternalevent value="Busy">

         <text>

           All lines are currently busy.

           Please hang up and try your call again later.

         </text>

         <hangup/>

       </onexternalevent>



       <onexternalevent value="TimedOut">

         <text>

           There is no answer.

           Please hang up and try your call again later.

         </text>

         <hangup/>

       </onexternalevent>



       <onexternalevent value="Error">

         <text>

           A connection can not be made at this time.

           Please hang up and try your call again later.

         </text>



         <sendemail from="MyApp@here.com"

           to="YourEmail@there.net" type="debug">

           We caught an error in our application.  Details follow...

        </sendemail>



         <hangup/>

       </onexternalevent>



    </block>



  </block>



</callxml>

Notice the conference tag, <conference targetsessions="$session.EventsenderID;"/>, in the above script. This happens when our other script, (which we will see momentarily), has sent us an event named "Success". We conference the two sessions together so that there is direct voice interaction, (for example, in an office hold system, where you are waiting for "the Next Available Representative"). The session.EventSenderID variable is automatically created for you -- if there is an external event you will be able to access the origin through that variable.

Step 4: scripting the second file

All that remains now is to create our second file (remember to call it "newCall.xml"); that is, the one that actually places the outbound call and then sends back a message to the parent or first session. Here is the file reproduced in its entirety:



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

<callxml version="2.0">

  <block>

    <call value="$NumToCall;"

          maxtime="30s"/>



    <onanswer>

      <sendevent value="Success"

                session="$ParentSessionID;"/>

    </onanswer>



    <oncallfailure>

      <sendevent value="Busy"

                 session="$ParentSessionID;"/>

    </oncallfailure>



    <onmaxtime>

      <sendevent value="TimedOut"

                 session="$ParentSessionID;"/>

    </onmaxtime>



    <onerror>

      <sendevent value="Error"

                 session="$ParentSessionID;"/>

    </onerror>

  </block>

</callxml>

We now have several unfamiliar elements in this file. First of all, we see the actual out-bound calling element, "call":



 <call value="$NumToCall;" maxtime="30s"/>

Here we are dialing a number that we passed in as a variable from the first session/script. We direct it to call for no more than 30 seconds, (maxtime="30s"). Next we see the element to send a message between sessions is: sendevent. Like the call element, sendevent is very straightforward: send a value to another session. Now we can see why we created a variable named: ParentSessionID in our first script/session.

Step 5: upload, and try it out

Your hello world with call bridging (in Callxml) application is now done. Call the number associated with your Callxml application, and you'll find that the results of this Lesson will work just like the previous one -- except now we know how to a run element to to spawn multiple sessions!

CallXML 2.0 source code.

What we covered:

Beginning with our basic CallXML structure, we added more CallXML to our block and assigned a $session.ID and a telephone number to call, each with their own variables
We used the run element like an http method to start a new session
Introduced the wait</wait> element


Created our onExternalEvent handlers, like: <onexternalevent value="Success">, which will catch events spawned from the new session started by: newCall.xml



















            



                        
            
            
            
            
            
                
                
                
                
                
                
                
                
                
                
                
            







































  ANNOTATIONS: EXISTING POSTS

0 posts - click the button below to add a note to this page













login







            




  Introduction to Call Bridging   |  TOC   |  Introduction to Token Calls   

© 2011 Voxeo Corporation  |  Voxeo IVR  |  VoiceXML & CCXML IVR Developer Site