SIP Connector

LiveSwitch Server allows users to dial into calls, conferences, and broadcasts running on LiveSwitch using the SIP Connector, which acts as a proxy between the Media Server and remote SIP user agents.

The SIP Connector requires an account with a SIP trunking provider. Supported features include:

  • Trunk registration.
  • Multiple trunks.
  • Static inbound channel routing.
  • Dynamic inbound channel routing.
  • Dynamic outbound trunk routing.
  • Dynamic outbound caller ID.

Trunk

Trunk Requirements

Outbound Calling

Outbound calling requires that the trunk supports receiving delayed offers:

  1. LiveSwitch sends an empty INVITE.
  2. LiveSwitch receives an ACK with an SDP offer.
  3. LiveSwitch sends an OK with an SDP answer.

Inbound Calling

Inbound calling requires that the trunk always sends early offers:

  1. LiveSwitch receives an INVITE with an SDP offer.
  2. LiveSwitch sends an ACK with an SDP answer.
  3. LiveSwitch receives an empty OK.

Trunk Registration

If the trunk is configured to register, it will do so with the supplied credentials (domain, username, password, and optional auth ID).

Multiple Trunks

When multiple trunks are configured, outbound calls are routed to the first available.

Dynamic outbound trunk routing is also available (see below).

Trunk Configuration

You must have an account with a SIP provider to use the LiveSwitch SIP Connector. There are several providers that provide free trials, which you can use to get started. Once you have a provider, you can configure them in this section to tell the LiveSwitch SIP Connector how to connect with them.

  • Domain - The SIP provider domain.
  • Transport - The protocol to use to connect to the SIP provider. Supported protocols are UDP, TCP, and TLS. Please note that the trunk itself must support the configured protocol.
  • Register - Whether or not this SIP provider sends a registration request.
  • Can Terminate - Whether or not we can make outbound calls from this SIP provider.
  • Username - SIP Provider credentials.
  • Password - SIP Provider credentials.
  • Authorization Id - Some SIP providers use an auth id in addition to the username and password. 

Sip Routing Mechanism

The following routing mechanisms provide different means to make an inbound/outbound call.

Static Inbound Channel Routing

An optional application-level inbound mapping configuration can be provided to select a channel for an inbound call.

The configuration is static and consists of a set of records with following properties:

SIP Username string (primary key) The URI in the "To" header of the inbound INVITE message.
Channel ID string The ID of the channel to which the call should be routed.

Dynamic Inbound Channel Routing

An optional deployment-level inbound webhook URL can be provided to select an application and channel for an inbound call:

Request

The request is sent using the POST method to the URL as JSON with the following fields:

headers

Dictionary<string, string>

The headers from the inbound INVITE message.
sdp string The SDP offer from the inbound INVITE message.

Response

The response must be JSON and must include the following required fields:

applicationId

string

The ID of the application to which the call should be routed.
channelId string The ID of the channel to which the call should be routed.

The response may include the following optional fields:

userId string

The user ID to use for channel-level upstream connection open/close notifications.

(Defaults to the URI in the "From" header from the inbound INVITE message if not specified.)

Console SIP Configuration

For configuring Deployment-level Inbound Routing via your console please see the SIP Configuration section of our Console Configuration docs.

Dynamic Outbound Trunk Routing

An optional deployment-level outbound webhook URL can be provided to select a trunk for an outbound call.

Request

The request is sent using the POST method to the URL as JSON with the following fields:

applicationId string The ID of the application from which the call is originating.
channelId string The ID of the channel from which the call is originating.
clientId string The ID of the client from which the call is originating.
userId string The optional user ID of the client from which the call is originating.
sipTrunks SipTrunk[] The available trunks.

Each trunk is a record with the following properties:

id string The trunk identifier.
authId string The auth ID from the trunk credentials.
username string The username from the trunk credentials.
domain string The domain from the trunk credentials.

Response

The response must be JSON and must include the following required fields:

sipTrunkId string The trunk to which the call should be routed.

Console SIP Configuration

For configuring Deployment-level Outbound Routing via your console please see the SIP Configuration section of our Console Configuration docs.

SIP Inbound Mapping Configuration

If you are using SIP integration (via SIP Connector), then we require a way to map incoming SIP Invites to a particular Channel. Provide the SIP URI and the Channel to which you wish to route incoming SIP requests. For example, you can add configuration to route invites from user@host.port into the my-awesome-channel channel.

Console SIP Configuration

For configuring Channel-level Outbound Caller ID via your console please see the SIP Outbound Caller ID Configuration section of our Console Configuration docs.

Dynamic Outbound Caller ID

An optional channel-level Sip Outbound Caller ID Configuration can be provided to configure the contact used in the "From" header for outbound INVITE messages.

The configuration is static consists of a single record with following properties:

Display Name string

The display name to use in the "From" header in the outbound INVITE message.

(Defaults to null if not specified.)

Username string

The username to use for the URI in the "From" header in the outbound INVITE message.

(Defaults to the username from the trunk credentials if not specified.)

Both properties support a basic curly-brace template format (e.g. {userAlias}-{userId}) with the following variables available:

id string The ID of the client from which the call is originating.
deviceId string The optional device ID of the client from which the call is originating.
deviceAlias string The optional device alias of the client from which the call is originating.
userId string The optional user alias of the client from which the call is originating.
userAlias string The optional user ID of the client from which the call is originating.
tag string The optional tag of the client from which the call is originating.
roles string[] The optional roles of the client from which the call is originating.
region string The optional region of the client from which the call is originating.

SIP Outbound Caller ID Configuration

Outbound caller ID can now be set for your SIP Connector using the SIP Outbound Mapping Configuration properties Display Name Pattern and Number Pattern. You can configure both of these properties if you wish. A SIP URI may contain name and number segments. These two pattern properties act as a template so you can set your SIP URI name and number segments to whatever you want. Using `{}`, they swap in variables from the ClientInfo object. For example: "{userAlias}-{userId}" is a valid pattern.

Twilio Specific Caller ID Requirements

By default, the SIP Connector uses username as the caller ID when placing outbound calls. This is usually overwritten by your SIP provider. However, with Twilio, outbound calls will fail unless either a Twilio-purchased number, or a verified number, is set as your SIP Connector caller ID.

SIP Configuration

Dial Plan

The two Webhook URLs are used to specify HTTP or HTTPS endpoints that will be hit when a call does not match any of the dial plan's mappings provided by your SIP Inbound Mapping Configuration.

Webhook Inbound URL

If an inbound web hook is provided, and a call does not match a configured dial plan, then an inbound call will trigger a simple HTTP request to the provided URL. The HTTP request will be delivered as a POST request, with a Content-Type of application/json. The body of the request itself will contain a JSON object with information on the original SIP INVITE request. This object will contain two top-level keys, headers and sdp.

The headers key is a nested JSON object, where each key represents a header from the INVITE request, and with each value representing the corresponding value of the SIP header. The sdp key will contain the SDP message from the INVITE request. A request will look similar to the following example:

{
  "headers": {
    "From": "\"Frozen Mountain\" <sip:frozenmountain@10.0.0.0>",
    "Content-Type": "application/sdp",
    ...
  },
  "sdp": "v=0\r\no=alice 2890844526 2890844526 IN IP4 host.atlanta.example.com..."
}

Using the query parameters and the SIP INVITE request, your web hook must issue an HTTP response of type application/json, containing the following parameters:

  • applicationId: the application id to map the request to
  • channelId: the channel id to map the request to
  • userId: the user id to map the request to (optional)

Each of these parameters should be a top-level key of a JSON object. An example JSON response will look similar to the following:

{
  "applicationId": "my-app",
  "channelId": "581233",
  "userId": "john@doe.com"
}

Webhook Outbound URL

In the case that you have configured more than one SIP trunk an outbound web hook provides a mechanism for determining which trunk to use. If an outbound web hook is provided, and a call does not match a configured dial plan, then an outbound call will trigger a simple HTTP request to the provided URL.  The HTTP request will be delivered as a POST request, with a Content-Type of application/json

An example JSON response will look similar to the following:

{
  "sipTrunkId": "my-sip-trunk-id"
}

Port

Overrides the default SIP port.

Port

Unless you have a specific reason to alter the port, you should leave it as 5060.  Modifying this can cause confusion, as many applications will expect the port to be 5060.