SIP IVR Routing

An Interactive Voice Response (IVR) is an effective and efficient way to route inbound phone calls to LiveSwitch via the SIP Connector. As IVR constraints and characteristics vary, LiveSwitch supports the following routing options:

Routing Models

Number Routing

Number routing is simply forwarding calls from your IVR to phone numbers from a SIP trunk that are mapped to application/channel IDs in your SIP Connector configuration. This is especially useful for environments where direct call-in is configured and you want to migrate to an IVR call-in model.

The IVR must support connecting calls to external phone numbers:

<Connect number="18883796686" />

The call flow typically looks like this:

  1. IVR answers the call and then prompts for user input.
  2. IVR connects the call to one of the SIP trunk phone numbers based on user input.
  3. SIP trunk routes call to your SIP Connector.
  4. SIP Connector routes call to the Application ID or Channel ID mapped to the phone number.
Note

This routing model typically results in double-billing: IVR in/out rate + SIP trunk in/out rate.

Extension Routing

Extension routing skips the SIP trunk and routes the call directly from the IVR to extensions that are mapped to Application ID or Channel ID in your SIP Connector configuration. This has two key advantages over number routing:

  • No need to purchase phone numbers from a SIP trunk.
  • Only pay the IVR in/out rate. No double-billing.

You must expose the SIP Connector through the firewall for unsolicited inbound SIP messages.

Note

Always configure your firewall rules to restrict inbound traffic to your SIP server port (typically 5060) and the known IP ranges of your IVR provider.

The IVR must support connecting calls to external SIP endpoints.

Pseudo-code IVR control block:

<Connect sip="sip:my-extension@my-sip-connector.xyz" />

The call flow typically looks like this:

  1. IVR answers the call and then prompts for user input.
  2. IVR connects the call to one of your SIP Connector extensions based on user input.
  3. SIP Connector routes call to the Application ID or Channel ID mapped to the extension.

Header Routing

Header routing allows the IVR to manage all the routing details instead of relying on mappings in your SIP Connector configuration. The consolidation of routing details into one place can make it easier to maintain and implement change control.

As with header routing, the SIP Connector must be exposed through the firewall for unsolicited inbound SIP messages.

Note

Always configure your firewall rules to restrict inbound traffic to your SIP server port (typically 5060) and the known IP ranges of your IVR provider.

As with header routing, the IVR must support connecting calls to external SIP endpoints, but it must also support adding custom headers to the outbound INVITE message. The call is routed to the Application ID or Channel ID indicated in the lss and lsc headers.

Pseudo-code IVR control block:

<Connect sip="sip:my-ivr@my-sip-connector.xyz">
  <Headers>
    <lsa>my-application-id</lsa>
    <lsc>my-channel-id</lsc>
  </Headers>
</Connect>
Note

The Application ID and Channel ID must be URI-encoded, such as encodeURIComponent.

The call flow typically looks like this:

  1. IVR answers the call and then prompts for user input.
  2. IVR connects the call to one of your SIP Connector extensions based on user input and then adds Application ID or Channel ID headers.
  3. SIP Connector routes call to the Application ID or Channel ID in the headers.

Advanced Options

Explicit User IDs

Some IVRs replace the caller number with the IVR number when connecting the inbound call to the SIP Connector. If this happens, your LiveSwitch application shows a user ID that reflects the IVR number instead of the caller number.

If you are using extension or header routing, you can resolve this problem by explicitly setting the user ID.

For Extension Routing

Append lsu= and the caller number to the query part of the SIP URI to sign the request.

Pseudo-code IVR control block:

<Connect sip="sip:my-extension@my-sip-connector.xyz?lsu=16041235789" />
Note

The user ID must be URI-encoded, such as encodeURIComponent.

For Header Routing

Add a lsu header with the caller number to set the user ID.

Pseudo-code IVR control block:

<Connect sip="sip:my-ivr@my-sip-connector.xyz">
  <Headers>
    <lsa>my-application-id</lsa>
    <lsc>my-channel-id</lsc>
    <lsu>16041235789</lsu>
  </Headers>
</Connect>
Note

The user ID must be URI-encoded, such as encodeURIComponent.

Request Signatures

Signing outbound requests is strongly recommended for the additional security it provides.

If you are using extension or header routing, signing means adding an expiry and signature using one of the following algorithms and encodings:

Algorithms

  • hm128 - HMAC-MD5 (128 bits)
  • hs160 - HMAC-SHA-1 (160 bits)
  • hs256 - HMAC-SHA256 (256 bits)

Encodings

  • b64 - Base64 (valid characters are A-Za-z0-9+/=, for space-restricted use cases)
  • hex - Hexadecimal (valid characters are a-f0-9, for charset-restricted use cases)
Note

For Base64, you may trim the padding (=) off the end to save space.

The expiry is a Unix timestamp measured in seconds since epoch. If the SIP Connector rejects inbound calls with an expiry in the past, ensure that your server synchronizes its system clock with a reliable timestamp server.

To generate a signature:

  1. Create the message to be signed by joining these values together in the following order using a new-line (\n) separator: a. Application ID b. Channel ID c. User ID d. Expiry
  2. Sign the message using your algorithm of choice and the Signature Secret from your SIP Connector configuration.
  3. Convert the binary signature into text using your encoding of choice.
  4. Concatenate the encoding ID, algorithm ID, and encoded signature.

Psuedo-code signature snippet:

const CryptoJS = require("crypto-js");

var hmac = (algorithmId, input, secret) => {
    switch (algorithmId) {
        case 'hm128': return CryptoJS.HmacMD5(input, secret);
        case 'hs160': return CryptoJS.HmacSHA1(input, secret);
        case 'hs256': return CryptoJS.HmacSHA256(input, secret);
    }
    throw new Error('Unrecognized algorithm.');
};

var encode = (encodingId, input) => {
    switch (encodingId) {
        case 'b64': return CryptoJS.enc.Base64.stringify(input).replace(/=+$/,'');
        case 'hex': return CryptoJS.enc.Hex.stringify(input);
    }
    throw new Error('Unrecognized encoding.');
};

var getSignature = (applicationId, channelId, userId, signatureSecret, algorithmId, encodingId) => {
    var expiry = Math.floor(Date.now() / 1000) + 300; // 5-minute expiry
    var input = [applicationId || '', channelId || '', userId || '', expiry].join('\n');
    var output = encode(encodingId, hmac(algorithmId, input, signatureSecret));
    return encodingId + algorithmId + output;
};

For Extension Routing

Append lse=, the expiry, lss=, and the signature to the query part of the SIP URI to sign the request.

Pseudo-code IVR control block:

<Connect sip="sip:my-extension@my-sip-connector.xyz?lse=1224486000&lss=b64hm128llIah1XxLtd9qeuEpWhApg" />
Note

The signature must be URI-encoded, such as encodeURIComponent.

For Header Routing

Add a lse header with the expiry and a lss header with the signature to sign the request.

Pseudo-code IVR control block:

<Connect sip="sip:my-ivr@my-sip-connector.xyz">
  <Headers>
    <lsa>my-application-id</lsa>
    <lsc>my-channel-id</lsc>
    <lsu>16041235789</lsu>
    <lse>1224486000</lse>
    <lss>b64hm128llIah1XxLtd9qeuEpWhApg</lss>
  </Headers>
</Connect>
Note

The signature must be URI-encoded, such as encodeURIComponent.

Syntax Reference

For Extension Routing

The following parameter names are defined:

lsa=<application-id>
lsc=<channel-id>
lsu=<user-id>
lse=<expiry>
lss=<encoding-id><algorithm-id><signature>

You can add multiple fields to the query part of the SIP URI.

For Header Routing

The following header names may be used:

LSA: <application-id>
LSC: <channel-id>
LSU: <user-id>
LSE: <expiry>
LSS: <encoding-id><algorithm-id><signature>

The SIP Connector ignores prefixes and casing in header names to maximize interoperability with third-party IVRs that may append arbitrary prefixes or restrict the use of certain characters.

For example, the following header names are considered identical:

lsa
LSA
X-lsa
FM-LSA
FM-X-LSA

Definitions

application-id = encodeURIComponent(*CHAR)
channel-id     = encodeURIComponent(*CHAR)
user-id        = encodeURIComponent(*CHAR)
expiry         = *DIGIT    ; Unix timestamp (seconds since epoch)
encoding-id    = "b64" /   ; Base64
                 "hex"     ; Hex
algorithm-id   = "hm128" / ; HMAC-MD5 
                 "hs160" / ; HMAC-SHA1
                 "hs256"   ; HMAC-SHA256
signature      = encoding-id + algorithm-id + encodeURIComponent(*CHAR)