SIP Connector

Session Initiation Protocol (SIP) is a text-based signaling protocol used to manage media sessions between two IP-connected endpoints. It's the primary signaling protocol used by VoIP systems when establishing calls. LiveSwitch supports SIP configuration to connect telephone devices to the Media Server.

Note

LiveSwitch doesn't support making video calls with the SIP Connector.

You can configure SIP for your LiveSwitch application to accept inbound calls or make outbound calls.

Requirements

You need to set up a SIP trunk account with a third-party SIP provider or host your own SIP trunk server with the following requirements:

If you want your app to support outbound calling, the SIP trunk must support receiving delayed offers. The following describes the outbound call workflow:
1. LiveSwitch SIP Connector sends an empty INVITE to the SIP trunk.
2. LiveSwitch SIP Connector receives an ACK with an SDP offer to the SIP trunk.
3. LiveSwitch SIP Connector sends an OK with an SDP answer to the SIP trunk.
If you want your app to support inbound calling, the SIP trunk must support sending early offers. The following describes the inbound call workflow:
1. LiveSwitch SIP Connector receives an INVITE with an SDP offer to the SIP trunk.
2. LiveSwitch SIP Connector sends an ACK with an SDP answer to the SIP trunk.
3. LiveSwitch SIP Connector receives an empty OK to the SIP trunk.

Trunk Configuration

Configure your SIP trunk so that your LiveSwitch application can support making inbound or outbound calls.

In the LiveSwitch Console > Deployments > SIP Configuration section, click NEW to add a new trunk.
Enter your SIP trunk's domain name.
Select the protocol that connects the SIP connector with the SIP trunk. Available options are UDP, TCP, and TLS.
If your SIP trunk requires a registration request, select the Register? checkbox.
Enter the following information provided by your SIP provider:
- Username
- Password
- Authorization ID
- Outbound Proxy
- Default Register Expiry
Tip

The Default Register Expiry is 300 seconds if not provided, and applies to most use cases. It's possible that your SIP provider requires a different time. If so, enter it in the field.

Map Inbound Calls Statically

You can map incoming SIP Invites to specific channels of your app. For example, you can map a phone number to an online meeting room so that users can dial into the meeting.

In the LiveSwitch Console > Applications > SIP Inbound Mapping Configuration section, click NEW to add a new mapping.
In the URI field, enter the SIP invite identifier, such as the call-in phone number for an online meeting if you are using a SIP trunk provided by a third-party provider. The URI must be a registered number from your SIP provider.
In the Channel field, enter the ID of the channel that maps to the SIP invite.

Customize Outbound Caller ID

By default, the SIP Connector uses username as the caller ID when placing outbound calls. However, certain SIP providers, such as Twilio, require the caller ID to be either a Twilio-purchased number or a verified number. You can customize the outbound caller ID to meet this kind of requirement. To do so, in the LiveSwitch Console > Applications > Channels > SIP Outbound Caller ID Configuration section, enter Display Name Pattern and Number Pattern. You can set those two patterns using the curly brace template format with the properties from the object. For example, {UserAlias}-{UserId}.

Customize Dial Plan Using Webhooks

Webhooks are user-defined HTTP callbacks that can send event-triggered notifications or updates to an external web server. You can use webhooks to hook your own processing into LiveSwitch events. LiveSwitch sends out webhook event updates as an HTTP POST request with the body formatted in JSON.

You can use webhook to map inbound calls, route outbound calls, and get notified by canceled calls from LiveSwitch SIP Connector.

Map Inbound Calls Dynamically

You can use a webhook to dynamically map inbound calls according to your app's logic in addition to the static mapping. For example, you can create logic to map incoming calls to available agents for a call center app. When a call comes in, and the available agent is found, you create a new meeting room for that agent and maps the call into the room.

To map inbound calls, in the LiveSwitch Console > Deployments > SIP Configuration section, enter your Webhook Inbound URL. If an inbound call does't match any static mapping, LiveSwitch sends an HTTP POST request to the provided webhook URL. Your webhook must return the application and channel for mapping the calls.

The HTTP request is a Content-Type of application/json. The JSON object includes the following properties:

Property	Type	Description
headers	JSON	The headers from the inbound INVITE message.
sdp	string	The SDP offer from the inbound INVITE message.

An example request looks like the following:

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

Your webhook HTTP response must be the Content-Type of application/json with the following properties:

Property	Type	Required	Description
applicationId	string	Required	ID of the application that maps to the call.
channelId	string	Required	ID of the channel that maps to the call.
userId	string	Optional	ID of the user for channel-level upstream connection open/close notifications. Defaults to the URI in the "From" header in the inbound INVITE message.

An example response looks like the following:

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

Get Notified of Canceled Calls

To get notified of canceled calls using a webhook, in the LiveSwitch Console > Deployments > SIP Configuration, enter your Webhook Inbound Cancel URL. If an inbound call is canceled, LiveSwitch sends an HTTP POST request to the provided URL. Your webhook response doesn't need to contain any information.

The HTTP request is a Content-Type of application/JSON. The JSON object includes the following properties:

Property	Type	Description
headers	JSON	The headers from the inbound INVITE message.

An example looks like the following:

{
  "headers": {
    "From": "\"Frozen Mountain\" <sip:frozenmountain@10.0.0.0>",
    "Content-Type": "application/sdp",
    ...
  }
}

Route Outbound Calls

If you have configured more than one SIP trunk, LiveSwitch routes the outbound calls to the first available one. You can use webhook to route outbound calls to the specified SIP trunk. For example, suppose you have SIP trunks configured for different regions. You probably want to route calls originated from Europe using the SIP trunk configured for Europe to avoid long-distance calls.

To route outbound calls, in the LiveSwitch Configuration Console > Application > SIP Configuration section, enter your Webhook Outbound URL. If an outbound call happens, LiveSwitch sends an HTTP POST request to the provided URL. Your webhook must return the SIP trunk ID for making the outbound call.

The HTTP request body is a Content-Type of application/json. The JSON object includes the following properties:

Property	Type	Description
applicationId	string	ID of the application where the outbound call originates.
channelId	string	ID of the channel where the outbound call originates.
clientId	string	ID of the client where the outbound call originates.
userId	string	ID of the user who originates the call.
sipTrunks	JSON array	List of all SIP trunks you have configured in LiveSwitch. If your webhook already knows the SIP trunk IDs, and you don't want to include the trunk list in the request, select the Exclude SIP Trunks checkbox.
id	string	ID of the SIP trunk.
authId	string	Authentication ID of the SIP trunk.
username	string	Username of the SIP trunk.
domain	string	Domain name of the SIP trunk.

An example response looks like the following:

{
  "applicationId": "my-app",
  "channelId": "581233",
  "clientId": "my_client_id",
  "userId": "john@doe.com",
  "sipTrunks":[
     {
        "id": "my-sip-trunk-1",
        "authId": "dfsdf1234",
        "username": "my_sip_user1",
        "domain": "www.domain1.com"
     },
     {
        "id": "my-sip-trunk-2",
        "authId": "dfsdf1234dsd",
        "username": "my_sip_user2",
        "domain": "www.domain2.com"
     }
     ]
}

Your webhook HTTP response must be a Content-Type of application/json with the following properties:

Property	Type	Required	Description
sipTrunkId	string	Required	ID of the SIP trunk to route the call.

An example response looks like the following:

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

Configure SIP Connector Ports

You can configure the port that the SIP Connector uses to communicate with the SIP trunks. To do so, in the LiveSwitch Console > Deployments > SIP Configuration section, enter the Port.

Note

Unless you have a specific reason, you should use the default value of 5060 because most SIP trunks use this value.

Signature Secret

You can enter a signature secret to be used to route inbound calls into the SIP Connector with the Application ID and Channel ID in the headers. Signature secret is like a password and you can use any characters for it. For more information on how to use it, refer to the Request Signatures section in the SIP IVR Routing topic.

SIP Connector

Note

Requirements

Trunk Configuration

Tip

Map Inbound Calls Statically

Customize Outbound Caller ID

Customize Dial Plan Using Webhooks

Map Inbound Calls Dynamically

Get Notified of Canceled Calls

Route Outbound Calls

Configure SIP Connector Ports

Note

Signature Secret