Prophecy 2006

After a long hiatus — I've been too busy with several crash projects to contribute — today I will reveal one of my major secret weapons for Prophecy programming.

Let's outline the problem first. According to the CCXML specification, I am allowed to connect two conferences togeher by using a "join" element. But on current Voxeo platforms, that does not work. The only way to join a conference to another conference is through a call: one end of the call connects to one conference, and the other end to another conference.

There's a similar issue if I want to record a conference, or if I want to play an audio file into a conference. I can't make a connection directly into the conference; I have to connect one end of a call into a conference and the other end to something that plays or something that records.

Now this poses a major problem. Let's go through the steps of connecting two conferences together.

• In one of the conferences, start a call using the "createcall" element.
• The connection ID is available once the call is created, so the "starting" end of the call can be easily connected to the conference.
• The call then is answered by a CCXML script.
• The CCXML script — I call this type of script an "endpoint" — connects to the other conference via "join" element.
• Now the two conferences are connected — right?

Well, no: it doesn't actually work that way. When the endpoint script answers the call, it has absolutely no information about how the call started. How is the endpoint script supposed to know the conference ID to which to connect the call? The "join" element needs both the connection ID of the call — the endpoint script has that through the connection.connected event, of course — as well as the conference ID of the conference. But how does the endpoint script get this conference ID? After all, the script started up when the "starting" conference initiated an ordinary SIP call, and the endpoint script is simply answering a call. How is the endpoint script supposed to have the conference ID? The information isn't included in any of the setup information for the call. How can this ever work?

The current Voxeo recommendation use the following trick for CallXML: create conferences with well-known names, and then create specific scripts that connect to those conferences. That is, when the "starting" conference initiates a SIP call, it calls a number that has a specific script that will connect to a specific conference, by name.

Well... that may work with CallXML, but that's a slim reed for CCXML. CCXML under Prophecy is a bit touchy about conference names; while you can specify a conference name, Prophecy will append a string to the name. Furthermore, this work-around requires that you pre-configure the system and maintain a listing of SIP phone numbers and which conferences they connect to. You have to plan in advance of the call which conferences connect where and to which scripts. In other words, in any large system or a system where you might have to make changes, you will easily get an administrative and debugging nightmare.

So, here's what I do: I cheat. When the "starting" conference creates the call, I set the caller ID of the call I create to the session ID of the "starting" conference's script. When the endpoint script starts, it now has a crucial piece of information by looking at the caller ID: the session ID of the "starting" conference script, which means it now has a way to communicate with the CCXML script that ultimately created the call.

My next step after the call is answered is to have the endpoint script send a message to the "starting" conference that includes the endpoint script's session ID. Now the two scripts have each other's session IDs and they can trade information.

In the case when I want to use he endpoint script to connect to a conference, I have the "starting" conference send the conference ID of the "other" conference to the endpoint script. In the case where I want to record a call or play an audio clip, the "starting" conference will send the endpoint script the appropriate information (e.g., the URL of the audio clip to play).

Here's a sequence that actually will connect two conferences together:

• In one of the conferences, start a call using the "createcall" element.
• The connection ID is available in the "starting" conference's script once the call is created, so the "starting" end of the call can be easily connected to the conference.
• The call is answered by a CCXML "endpoint" script.
• The CCXML endpoint script gets the session ID of the "starting" script by examining the caller ID.
• The endpoint script sends its session ID to the "starting" script.
• The starting script sends the conference ID of the conference it wishes to connect to to the endpoint script.
• The endpoint script issues a "join" between it and this conference ID.
• Now the two conferences are connected.

This idea of using caller ID to send the session ID allows me to extend the design pattern of inter-communicating scripts that I use throughout my multi-script applications, and most importantly does not require any pre-configuration of conference IDs. A single phone number has an endpoint script attached, and any number of conferences can use this endpoint phone number for multiple purposes — as each call comes in, it starts a new instance of the script, which operates independently of any other instance.

This is a simple, well-tested, and in my opinion the most elegant way to have these sort of scripts communicate with each other.