SIP Connector

Introduction

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

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 outbound 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 app can support making inbound or outbound calls. 

1. In the LiveSwitch Configuration console → DEPLOYMENTS → SIP Configuration section, click New to add a new trunk.
2. Enter your SIP trunk's domain name.
3. Select the protocol that connects the SIP connector with the SIP trunk. Available options are UDP, TCP, and TLS. 
4. If your SIP trunk requires a registration request, select the Register checkbox. 
5. Enter the following information provided by your SIP provider: 
   • Username
   • Password
   • Authorization ID
   • Outbound proxy

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. 

1. In the LiveSwitch Configuration console → APPLICATIONS → SIP Inbound Mapping Configuration section, click NEW to add a new mapping.
   
2. 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.
3. 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 Configuration console → APPLICATIONS → Channels → SIP OUtbound Caller ID Configuration section, enter Display Name Pattern and Number Pattern. You can set those two patterns using 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 and are used for apps to "speak" to each other and get notified automatically when something new happens.

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 application'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 Configuration console → APPLICATION → SIP Configuration section, enter your Webhook Inbound URL. If an inbound call happens and the call does not 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:

An example request looks like the following:

{
  "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..."
}

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

An example response looks like the following:

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

Get Notified with Canceled Calls

If you want to get notified with canceled calls, in the LiveSwitch Configuration console → APPLICATION → 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 does not need to contain any information.

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

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 requests 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:

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:

An example response looks like the following:

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

Configure SIP Connector Ports

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