Introduction

Normally, the system routes are stored in the "outroutes" table in the database and peer call costs in the "outcosts" table. If the system is so configured, a third party web application can override the data in these tables. This works in a similar way to the "Ask web URL" destination type.

Developers are warned that this is an advanced use of Enswitch. This should not be attempted unless already very familiar with configuring call routing and pricing using the Enswitch web interface. To ensure performance, minimal error checking is done of the data returned by the web server, but returning incorrect data can lead to calls failing to route, being billed incorrectly, or long post dial delays. It is vital to test this on a test machine before configuring on a production system.

Configuration

  • If you wish to use this for call routing, set the "URL for routes" setting under Global » Settings » Configuration to the URL providing the routing data.
  • If you wish to use this for peer call costs, set the "URL to fetch costs from" setting for the peer URL providing the call costs data. This should not be the same URL as for routing, as they have different inputs and outputs.

Data flow

  1. Any time Enswitch needs to access data configured to use the web lookup, it will make an HTTP POST to the appropriate URL. Examples of when this is done are:
    • Both routing and peer costs at the start of each call, to route the call and to calculate how long to let the call run for before the customer runs out of balance.
    • Peer costs at the end of the call, to bill the call.
    • Any time a user uses the Reports » View rate plan menu. Depending on the data the user is viewing, and how call pricing is configured, routing, peer pricing, both, or neither may be looked up. This is a good way to test without having to make calls.
    • The system recalculates its least cost routing (LCR) tables.
  2. There may be multiple lookups per call, for example if a hunt group makes outbound calls to multiple PSTN destinations.
  3. The web server must respond to each lookup with a text document with the fields listed in the "output fields" sections below. Normally this document would be dynamically generated using a CGI script or similar.
  4. Enswitch will route and bill the call using the data provided.
  5. If the web request takes more than five seconds (including time for DNS lookup) the lookup will be deemed to have failed, and the data in the database will be used instead.

Routing input fields

Enswitch will pass the following fields in the POST to supply details of the call when doing a routing lookup:

  • id: The ID of the row in the "outroutes" table that best matched the call details. The values in this row are the defaults used if the web server does not return them. 0 if no matching route was found in the database.
  • customer: The ID of the customer making the call. 0 if the lookup is not associated with any customer such as when the system is recalculating its LCR tables.
  • caller: The callerid. Empty string if not known, or if the lookup is not associated with any call such as when a user uses the Reports » View rate plan menu.
  • called: The called number. Empty string if the lookup is not associated with any called number such when a user uses the Reports » View rate plan menu » Outbound call costs menu.
  • media: The call media for billing purposes. "voice", "fax", or "message".
  • outgroup: The ID of the outbound group. Usually 0, but will be a positive value if a route for a particular outbound group is required such as when a user uses the Reports » View rate plan menu. This field will always be set if the called number is not set.

Routing output fields

The web server is expected to return a text document with content type "text/plain", and one field per line as in the sample below.

A sample document is:

outgroup: 123
peer1: 3
peer2: 2
peer3: 1

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:

  • outgroup: The ID of the outbound group to use to price the call.
  • peer1: The ID of the peer to route the call to.
  • peer2: The ID of the backup peer. Use 0 to have no backup peer.
  • peer3: The ID of the second backup peer. Use 0 to have no second backup peer.

If the web server does not return any of these fields, the database values will be used. If the "id" field sent in the request is 0, then the web server must return both the "outgroup" and "peer1" fields. Without these, it is not possible to route or bill the call, and the call will be rejected.

Cost input fields

Enswitch will pass the following fields in the POST to supply details of the call when doing a peer cost lookup:

  • id: The ID of the row in the "outcosts" table used to bill the call. The values in this row are the defaults used if the web server does not return them. 0 if no matching cost was found in the database.
  • direction: "in" if the call is inbound, "out" if the call is outbound.
  • start: The Unix timestamp when the call started, or the current timestamp if the lookup is not associated with a call.
  • customer: The ID of the customer being billed. Typically 2 for the system owner customer. 0 if the lookup is not associated with any customer such as when the system is recalculating its LCR tables.
  • caller: The callerid. Empty string if not known, or if the lookup is not associated with any call such as when a user uses the Reports » View rate plan menu.
  • called: The called number. Empty string if the lookup is not associated with any called number such when a user uses the Reports » View rate plan menu » Outbound call costs menu.
  • media: The call media for billing purposes. "voice", "fax", or "message".
  • outgroup: The ID of the outbound group used for the call. 0 if the lookup is not associated with a call.
  • outgroup_time: The ID of the outbound group time chunk used for the call. 0 if the lookup is not associated with a call.
  • plan: The ID of the rate plan. 1 if looking up a peer price, because peer costs are considered to belong to rate plan 1.
  • peer: The ID of the peer. 0 if looking up a rate plan price.

Cost output fields

The web server is expected to return a text document with content type "text/plain", and one field per line as in the sample below.

A sample document is:

connectfee: 0.10
included: 60
cost: 0.015
increment: 1
minimum: 0.00
message: 0.05

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:

  • connectfee: The price charged as soon as the call is answered.
  • included: The number of seconds after answering to start the per minute cost.
  • cost: The cost per minute.
  • increment: The per minute cost billing increment in seconds.
  • minimum: An overall minimum cost for the call if answered.
  • message: The cost to send a text message to this destination. It's only necessary to return this field if messaging is enabled, and the media type requested was "message".

All costs must be in the rate plan or peer's currency. If the web server does not return any of these fields, the database values will be used. If no cost was found in the database and the web server does not return values, the call is billed as being free. If the media type requested was "voice" or "fax", then the message field is not used and need not be returned. If the media type requested was "message", only the message field is used and all other fields need not be returned.

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.