Call Routing

Prophecy allows for complete control over the way calls are routed to and from your applications. An application may have one – or many – inbound telephone numbers. The call route process defines which application to play when a call is placed to a specific telephone number or DID. You may also define a default application to play when an unassigned number is dialed.

Accessing Call Routing Settings

From the Management Console, click "Routes" in the menu. Use this section to define new routes, delete old ones, or modify existing ones. Attaching applications to routes/telephone numbers is part of this process.

Setting a Default Application

When a call comes in, Prophecy looks at the number dialed and tries to match it to a Route; if it cannot find a Route ID, it runs the Default application. You can configure any application to be the default by setting the route to (*) (wildcard/asterisk).

Outbound Calls

All routes can also be used to place outbound calls by defining the route with a "token" instead of a normal telephony number. A token-initiated call allows developers to initiate a call via HTTP rather than calling into an application to start it. The simplest example is the creation of an outbound call by clicking a "submit" button on a web form. This is one of the most useful features in Prophecy (e.g., developers wishing to script a large series of outbound calls to numerous users at the same time). The most common application type for this capability is an outbound notification service.

From the Prophecy Home page you can access the Prophecy Token Tester for an easy way to quickly test your tokens, but the topic deserves a more detailed explanation here. While it might seem complicated, the process is surprisingly easy. Let's use the picture below and walk through the diagram's flow, step by step.

The Token Initiated Call

1. First, a general HTTP request is sent to the token API, including some query string variables identifying the requester (at the bottom of this document, you will find a quick reference for the API URLs and standard variables used).

2. The token API will reference the TokenID (which will be one of the querystring variables, e.g., tokenid=mytoken) against the internal provisioning database and identify the application against which the request should be forwarded. The internal provisioning database was defined in the "Routes" section of the Prophecy Management Console.

3. Prophecy will identify the start URL for the application and send off its own HTTP request to this document, passing session information and variables, including CallerID, CalledID, and any user-submitted variables.

4. The webserver delivers XML content back to Prophecy for execution (Note: the web server could have been a static XML file or a robust server-side, database-driven application in its own right – Prophecy does not care, as long as valid CallXML, CCXML, or VoiceXML is returned).

5. This content is returned to the platform and executed, and the call is placed. Up until now, only HTTP fetches have transpired, normally taking a fraction of a second in total.

6. Prophecy chooses one of the configured VoIP gateways to deliver the outbound call attempt.

7. The exit point from a typical network is a Session Board Controller (SBC), which communicates directly with the long-distance carrier cloud.

8. The long-distance carrier hands off the call to a mobile carrier, CLEC, or local phone company and the destination phone, be it a land-line or mobile, rings.

Should I use CCXML or VoiceXML?

Our general recommendation is to always utilize a CCXML "wrapper" for VoiceXML token applications, which provides much more granular call control for your applications. A great write-up on this type of deployment can be found here in our Blog.

Token APIs

Available Servlets
-----------------------
http://127.0.0.1:9998/SessionControl/VoiceXML.start
http://127.0.0.1:9999/SessionControl/CallXML.start
http://127.0.0.1:9999/SessionControl/CCXML10.start

Available Parameters
-----------------------
"tokenid" ==> (Required) Unique identifier for associated application mapping/routing information.
"numbertodial" ==> (Required for VoiceXML.start ONLY) Phone number to dial.
"resulturl" ==> Performs a 302 redirect to the specified URL (i.e., the response errorcode/result-set for the request would be redirected to the specified URL).
Example: http://127.0.0.1:9999/CCXML.start?tokenid=abc123&resulturl=http://myserver.com/results.php
"xmloutput=true" ==> Errorcode/result-set presented as XML.
Example: http://127.0.0.1:9999/CCXML.start?tokenid=abc123&xmloutput=true

ANNOTATIONS: EXISTING POSTS

bpcamac

10/8/2009 1:15 PM (EDT)

After configuring an application in Prophecy (with a route), use sip:ROUTE@127.0.0.1 where ROUTE is the route you defined for the application. You can also use sip:user@127.0.0.1 to test that you're at least getting to P9 (the default attendant app).

Applications

| TOC

| Token Tester