Introduction

Enswitch can consult an external web URL on how to route a call. It will pass details of the call to the URL, and will expect a response from the URL on where to route the call to. This allows any customer on the system to do dynamic routing of calls without the expense and complexity of their own telephone system.

To add a new web URL

1. Log in to the Enswitch web interface.
2. Go to Features » Web URLs.
3. Click the "New" button.
4. Enter the following:
   • A name for the web URL.
   • Optionally a description.
   • A HTTP URL that Enswitch will ask where to route the call.
   • Optionally, a HTTP URL that Enswitch will inform when the call has been answered.
   • Optionally, a HTTP URL that Enswitch will inform when the call has been hung up.
   • How long to wait for the web server before timing out.
   • A destination to route the call to on timeout or if the web server returns an error.
5. Click the "Save" button.
6. Set a number or feature code to route to the web URL.

Call flow

1. The call will be delivered to the feature, such as a number or feature code, that has "Ask web URL" set as its destination.
2. Enswitch will invoke the routing URL specified using HTTP POST, passing the form fields listed in the "input fields" section below.
3. The web server must respond with a text document with the fields listed in the "output fields" section below. Normally this document would be dynamically generated using a CGI script or similar.
4. Enswitch will route the call to the destination specified by the text document.
5. If the web request takes more than the timeout (5 seconds by default), including time for DNS lookup, it will be cancelled and the call will be routed to the timeout destination.
6. If the web URL or the web server specified URLs to be invoked on answer and on hangup, these will be done within a few seconds of these events. These URLs will be invoked multiple times if there are multiple legs.

Input fields

Enswitch will pass the following fields in the POST to supply details of the call:

• scustomer: The ID of the source customer. This will normally be the same as the customer. This field is deprecated and may be removed in future.
• stype: The source type. This will normally be "external" for an external number, or "phone" for a local telephone.
• snumber: The source number. The calling number or telephone. If a telephone, it will be the account rather than callerid.
• ctype: The called type. This will normally be blank, unless a call has been redirected.
• cnumber: The called number, as presented to the system.
• dcustomer: The ID of the destination customer. This will normally be the same as the customer. This field is deprecated and may be removed in future.
• dtype: The destination type that sent the call to the URL. For example, "number" or "code".
• dnumber: The destination number that sent the call to the URL, i.e. the number or feature code. For some dtypes such as IVR, this will be the ID of the object in the database.
• server: The hostname of the server invoking the URL.
• callid: An identifier for the call. The combination of server and callid will be different for every call. Legs of the same call will have the same callid but may have different uniqueids, depending on how they are routed within the server.
• uniqueid: An identifier for the call leg within the server at the telephony level.
• state: The state of the call. URLs invoked at the start of the call will be passed "ring" or "answer". URLs at the end of the call with be passed "hangup".
• patternmenu_digits: If the call passed through a pattern menu that collected DTMF digits from the caller, the digits collected.
• type: Sent only if System -> Configuration -> "Send 'type' in answer URL" is set to Yes. This parameter will have the value 'queue' when the call is answered within the context of a queue, 'callback' when the call is answered within the context of a callback and '' when any other type of call is answered.

In addition, the following fields will be passed on hang up:

• totaltime: How long the call ran for in seconds, including ringing.
• talktime: How long the call ran for in seconds, excluding ringing. For calls which were not answered, this will be 0.
• status: The status of the call. Normal values are "answer", "busy", "cancel", "congestion", or "noanswer", though other values indicating routing errors are possible.
• recording: The path to the recording file. If there was no recording, this will be an empty string.

Other fields may be added in future without warning.

Output fields

The web server is expected to return a text document with content type "text/plain". For the routing URL invoked at the start of the call, this should be one field per line as in the sample below. For the answer and hangup URLs, the text is ignored, so an empty document (apart from any HTTP headers your web server requires) should be sent.

A sample document is:

dtype: phone
dnumber: 1234567
answer_url: http://example.com/answer.cgi
hangup_url: http://example.com/hangup.cgi

Lines may be terminated by newline ("\n") or carriage return followed by newline ("\r\n"). Don't forget to add any HTTP headers required by your web server such as "Content-Type: text/plain\r\n\r\n". The fields to return are:

• dtype: The destination type to send the call to.
• dnumber: The destination number to send the call to.
• answer_url: A URL to invoke after the call has been answered. The URL will be invoked once for each leg. This field is optional, and overrides the setting specified in the web URL within Enswitch.
• hangup_url: A URL to invoke after the call has hung up. The URL will be invoked once for each leg. This field is optional, and overrides the setting specified in the web URL within Enswitch.