Prophecy 2006

Prophecy's semantic interpretation remains somewhat problematical at times. However, there's an issue with GSL semantic intepretation, one that can lead to hours of debugging, that I thought I might document.

Although I was testing on Prophecy, my client wanted to run the software on Voxeo's Voicecenter 5.5 system. I'd written the grammmars in XML format, and I'd used the usual W3C-style SIRS. Prophecy doesn't follow the W3 Semantic Interpretation for Speech Recogntion (SISR) specification, in that it doesn't use the "out" variable, doesn't support latest(), and some similar issues, but at least it supports standard ECMAScript.

When I converted to my W3 SISR semantic interpretation (SI) grammar to Nuance's GSL semantic interpretation, I ran into problems. I don't find GSL very intuitive, but it does work; the problem came when I tried to run my data. I'd included

Later in the code I collect each dayName into an array, and I pass that array back to VoiceXML. The goal is for a caller to say "I can work on Sunday, Tuesday, and Thursday" while ASR reports "Sunday Tuesday Thursday" as the interpretation.

But the darn thing simply would not work. After hours of fooling around, I finally noticed, when using the DTMF version of the grammar, that the GSL intepreter complained that Sunday wasn't a legal variable. I went into the code and swapped "Sunday" for "'Sunday'"; that is, I put a set of apostrophes into the code to see if I could convince GSL to treat Sunday as a string. This worked.

When I ported this grammar for testing on Voicecenter 5.5, it failed. The extra apostrophes must be absent when using Voicecenter 5.5, and they must be present when using Prophecy.

I expect that I should also mention that I noticed other problems working with P2006's GSL. Maybe it's me, but when I tried to include a tag element at the end of the top-level rule, nothing happened. In fact I couldn't get any tag elements to work in the top-level rules; I happen to have used them successfully in non-Prophecy systems, and I suspect that something isn't quite right.

In summary: If you're wondering why GSL grammars that work on one system don't seem to work on the other, or if your old GSL skills don't seem to produce working code on P2006, the reason may be incompatibility between the old systems and P2006. On the other hand, frankly, there's no good reason I can think of to write new grammars using GSL SI. I use W3C SISR whenever I can, and I think it's well worth the trouble of migrating between versions when Prophecy begins to support the full W3C SISR SI.

I've managed to get Freeswitch to make outbound calls to BusinessVoip. (See How-to book chapter.)

Next comes a chapter on how to route calls from Freeswitch to Propphecy, and how to route calls from Prophecy to Freeswitch to BusinessVoip to the PSTN.

Once Freeswitch registers with BusinessVoip, incoming calls to BusinessVoip will be routed to the Freeswitch User Agent. The next challenge is to route the calls to Prophecy.

In this setup, we'll assume that you have a BusinessVoip account that includes several different telephone numbers, all of which terminate at a single Prophecy server.

Here's the complete stanza for default_context.xml:

Here's a line-by-line explanation.

1. Create an "extension," that is, create a rule to handle a particular type of call:

2. Determine the conditions under which the rule is triggered:

The condition is triggered by a regular-expression match on the incoming number. In this case, we assume that any incoming call from BusinesVoip will have a distinct username — one that isn't used with any other type of incoming call.

3. Optionally, list some debugging information on the console and in the log file:

This action prints all the information available when a call arrives, and can help in debugging or in finding a unique key for a particular type of calls.

4. Play a ringing sound to the caller.

After all, we're about to transfer this call, and until Prophecy picks up the call, let's play a ringing tone.

5. Prepare to "bridge" the call.

Rather than re-direct the call, which doesn't seem to work with BusinessVoip — or if it does, I haven't figured it out yet — we're going to re-route the media through the Freeswitch server. This action turns off the re-direction of media.

6. Bridge the call to Prophecy. Because of limitations in the Sofia SIP UA agent, you must have the actual IP address of Prophecy to route to it.

Furthermore, since you may have several different Prophecy services running, you will want to route to the correct one. E.g., on Prophecy, you will have an callrouting.xml entry for "3125551212." To reach that number, you need to find out what nubmer the caller actually dialed. This information available in Freeswitch as the variable ${sip_to_user}. (To see what other information is available, you can use the optional "info" action as described above.

This assumes that there's a User Agent named "local" that routes local (behind-the-firewall) calls, and that the Prophecy server is located at IP address 192.168.32.54 and that it uses the default port of 5060 to receive calls.

Testing and debugging tips:

Start out by routing BusinessVoip calls to a known extension that works on Freeswitch directly, such as the "portaudio" console. After that works, and you can send and receive audio, you can attempt to route to Prophecy.

If your connection suddenly fails after 30 seconds or so, you likely need a STUN server or to fiddle with one of the external IP settings, as detailed in the section of how to register BusinessVoip.

The site update is completed, which ought to mean slightly better loading times. The site's theme may change in the near future.

I've added a section on how to use Freeswitch in the "Interfaces" section of the how-to book; more coming soon.

Finally, there shouldn't be much in the way of spam on these pages, but if you find some, use the links to report the spam. So far the filters are keeping the spam out, and the primitive captcha helps cut down on the imposters who register.

Here's how to register Freeswitch with BusinessVoip. This lets you receive incoming calls from BusinessVoip and route them to Prophecy, while at the same time gives you the flexibility to handle other incoming calls and make outgoing calls.

To start, I created a separate profile just for use with BusinessVoip:

I then created a gateway for BusinessVoip:

And then, since in the last "param" element I've asked to register Freeswitch as the place where BusinessVoip is to receive calls, I have to include a "registration" element:

Note that "my_sip_address" is the address behind behind the firewall.

Finally, the settings are:

In other words: tame, standard settings. Because of the way BusinessVoip operates, there doesn't seem to be a need for STUN.

This chapter of the book explains how to use Freeswitch, a SIP User Agent, to route calls to and from Prophecy.

I'm trying to register with BusinessVoip via Freeswitch, but I'm having no luck so far. Simple registration doesn't work; I wonder if it has something to do with the "RegistrationAddress" and similar variable, which have no counterpart on Freeswitch (or even Asterisk) to my knowledge.

Suggestions welcome, of course.

I've enabled Captcha for this web site, which will hopefully cut down on the number of false registrations.

I've got my hands on a Nokia E61, and I can't quite figure out how to make it connect to a Prophecy server.

Ordinary softphones don't need to register or have a proxy defined; I can just type in the name of the extension and the server (e.g., "connectionTest@flute") and I'll connect up.

With the Nokia, the darn thing seems to insist that it be "registered," and if the phone isn't registered I can't use the SIP stack at all.

I expect that I can run an Asterisk or Freeswitch server to act as a registrar and make connections between my phone and P2006, but it'd be far nicer to have the Nokia connect directly.

Any suggestions? If so, please include a comment with the answer.

My settings for the E61 include:

Proxy:
Server: flute (IP address)
Realm: flute

the rest set to None and/or defaults

For registration:
Server: None
Realm: flute

the rest set to None and/or defaults

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.