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.
SIP vs LiveSwitch Signalling
Wondering what SIP is and how it fits in with the WebRTC signalling layer? Signalling allows two endpoints (senders, receivers, or both) to communicate meta-information about the streaming connection between each other before actually setting it up. SIP stands for Session Initiation Protocol, and it is a text-based signalling protocol used to manage media sessions between two IP-connected endpoints. It is the primary signalling protocol used by VoIP systems when establishing calls and is the protocol used by LiveSwitch to connect telephone devices to its media server.
However, LiveSwitch signalling is not SIP. LiveSwitch uses WebRTC protocols for media streaming, and WebRTC excludes SIP and all other signalling protocols from the specification. WebRTC is "signalling agnostic". That said, it does enforce a high level of security and network efficiency by taking some pieces of the various signalling protocols and making them mandatory. This makes interoperability between WebRTC-based and SIP-based devices challenging since individual SIP providers may or may not support these mandatory components. The LiveSwitch SIP Connector takes care of this challenge. You just need to bring your own SIP trunk and the rest is handled.
The Role of the SIP Connector
Using the SIP Connector, inbound and outbound phone calls are handled with the SIP protocol and are bridged seamlessly with the application logic and media flow of your front-end web and native applications. It is also custom-tailored to meet the requirements of VoIP services, ensuring that calls always succeed. The media flow to and from each telephone is uniquely handled independently of all other connections using the LiveSwitch mixer (MCU), ensuring that security and speed is maximized wherever possible without compromising on interoperability. Any special SIP-related firewall rules only need be set up once on the server side.
Trunk
Trunk Requirements
Outbound Calling
Outbound calling requires that the trunk supports receiving delayed offers:
- LiveSwitch sends an empty INVITE.
- LiveSwitch receives an ACK with an SDP offer.
- LiveSwitch sends an OK with an SDP answer.
Inbound Calling
Inbound calling requires that the trunk always sends early offers:
- LiveSwitch receives an INVITE with an SDP offer.
- LiveSwitch sends an ACK with an SDP answer.
- 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.
Webhook Inbound URL 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 the 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.) |
|---|
In addition to the above, a second optional deployment-level inbound cancel webhook URL can be provided to notify when an inbound call is cancelled before it is answered:
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. |
|---|
Response
The response does not need to contain any information in this case.
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:
|
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:
|
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:
|
Webhook Inbound Cancel URL
If an inbound cancel webhook is provided, and an inbound call is cancelled before being answered, then the cancellation 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 one top-level key, headers.
The headers key is a nested JSON object, where each key represents a header from the original INVITE request, and with each value representing the corresponding value of the SIP header.
{
"headers": {
"From": "\"Frozen Mountain\" <sip:frozenmountain@10.0.0.0>",
"Content-Type": "application/sdp",
...
}
}
The HTTP response does not need to contain any information.
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.