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.

Call flow

  1. The call will be delivered to a feature, such as a number or feature code, that has "Ask web URL" set as its destination.
  2. Enswitch will invoke the URL specified using HTTP POST, passing the form fields listed in the "input fields" section below.
  3. The web server will 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 5 seconds, including time for DNS lookup, it will be cancelled and the call will be hung up.
  6. If the text document specified a URL to be invoked at the end of the call, this will be done within a few seconds of the call ending. This URL 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:

  • customer: The ID of the customer. This will normally be the same as the customer owning the number that invokes the URL.
  • 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 digits from the caller, the digits collected.

In addition, the following fields will be passed at the end of the call:

  • 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 URLs invoked at the start of calls, this should be one field per line as in the sample below. For URLs invoked at the end of calls, 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
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.
  • 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.

Copyright © Integrics Ltd., all rights reserved. Permission is granted for Enswitch partners, customers, and their resellers to copy the contents of this page into their own documentation and redistribute this to their customers.