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 privileges, 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="3.0">



  <do>

  </do>



</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="3.0">



  <do>

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

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



  </do>



</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="3.0">



  <do>

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

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



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



  </do>



</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="3.0">



  <block>

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

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



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



     <do label="HoldMusic"

           repeat="25">



             <playaudio format="audio/wav" value="Pulse.wav"/>



      </do>



  </block>



</callxml>

Step 3: adding our event handlers

We need to add our <on> event 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="3.0">





<block>

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

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



    <run value="newCall.xml"

  		submit="*"

 		method="get"

  		var="NewSessionID" />



    <do label="HoldMusic"

          repeat="25">



      <playaudio format="audio/wav"

          value="Pulse.wav"/>



     <on event="externalevent:Success">

        <log>*** EVENT = SUCCESS ***</log>

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

        <hangup/>

     </on>



     <on event="externalevent:busy">

        <log>*** EVENT = BUSY ***</log>

      <prompt value="Sorry, but the number is busy"/>

      <exit/>

     </on>





     <on event="externalevent:noanswer">

        <log>*** EVENT = NOANSWER ***</log>

      <prompt value="It looks like no one is home"/>

      <exit/>

     </on>





     <on event="externalevent:unreachable">

        <log>*** EVENT = UNREACHABLE ***</log>

      <prompt value="Your called party is unreachable"/>

      <exit/>

     </on>





     <on event="externalevent:rejected">

        <log>*** EVENT = REJECTED ***</log>

      <prompt value="Looks like your call recipient rejected the call"/>

      <exit/>

     </on>





     <on event="externalevent:unknown">

        <log>*** EVENT = UNKNOWN ***</log>

      <prompt value="Received an unknown call failure. Panic at will"/>

      <exit/>

     </on>



     <on event="externalevent:TimedOut">

        <log>*** EVENT = TIMED OUT ***</log>

      <prompt value="Max time for the call was reached, now disconnecting."/>

      <exit/>

     </on>



    </do>



  </block>



</callxml>

Notice the conference tag, <conference value="$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="3.0">



<do label="B1">



<call value="$NumToCall;"

      maxtime="30s" callerID="6666666666"/>



   <on event="answer">

    <log> *** CALL ANSWERED IN CHILD SESSION*** </log>

     <sendevent value="success"

               session="$ParentSessionID;"/>



            <conference value="$ParentSessionID;"/>

   </on>





    <on event="maxtime">

      <log>*** MAXTIME CALL EVENT CAUGHT IN CHILD SESSION *** </log>

      <sendevent value="timedout"

                session="$ParentSessionID;"/>

    </on>





    <on event="callfailure:unreachable">

      <log>*** UNREACHABLE EVENT CAUGHT IN CHILD SESSION ***</log>

      <sendevent value="unreachable"

                session="$ParentSessionID;"/>

    </on>





    <on event="callfailure:busy">

      <log>*** BUSY EVENT CAUGHT IN CHILD SESSION ***</log>

      <sendevent value="busy"

                session="$ParentSessionID;"/>

    </on>





<!-- note that an 'anonymous' callfailure handler will catch all call failure events -->

<!-- that do not have their own specific handler. if the developer employs this soultion, -->

<!-- note that this handler must reside below all other handlers -->



    <on event="callfailure">

      <log>*** RECEIVED AN ANONYMOUS CALLFAILURE EVENT ***</log>

    </on>





  </do>



</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 3.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
Created our onExternalEvent handlers, like: <onexternalevent value="Success">, which will catch events spawned from the new session started by: newCall.xml

ANNOTATIONS: EXISTING POSTS

lavanyasubbu

6/24/2010 1:17 AM (EDT)

on the newcall xml, i changed from

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

TO

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

Its not working. Looks like the second call isn't made. If i manully change it to a number it works. Can a variable not be used twice?

PS: As I was learning this, I wanted a friend's phone to ring with the same number/caller id as his phone (to freak-him-out)

voxeoJeffK

6/24/2010 2:19 AM (EDT)

Hello,

It looks like you are missing a ";" after the variable:

callerID="$NumToCall"

Note though that many carriers will not route a call where the callerID is the same as the destination.

Regards,
Jeff Kustermann
Voxeo Support

lavanyasubbu

6/24/2010 8:39 PM (EDT)

Jeff,
Sorry. I had the ";" and may have unknowingly removed it.

Your explanation makes sence and that could be the reason

VoxeoDante

6/24/2010 10:08 PM (EDT)

Hello,

You should also keep in mind that if you send a call to a phone with the callerID set to the the same as the number you are calling, you will send the call directly to voicemail and the user will never actually have the chance to answer.

Regards,
Dante Vitulano

qasimzee

12/1/2010 1:57 AM (EST)

priveleges should be privileges on the first line

voxeoJeffK

12/1/2010 2:19 AM (EST)

Hello,

Excellent, thank you. I've edited the documentation root, and this change will be in effect upon the next documentation build.

Regards,
Jeff Kustermann
Voxeo Support

Introduction to Call Bridging

| TOC

| Introduction to Token Calls