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.
Tip
This topic describes how to configure the SIP Connector. For step-by-step instructions, see Receive an Inbound SIP Call and Make an Outbound SIP Call.
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:
- LiveSwitch SIP Connector sends an empty INVITE to the SIP trunk.
- LiveSwitch SIP Connector receives an OK with an SDP offer from the SIP trunk.
- LiveSwitch SIP Connector sends an ACK 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:
- LiveSwitch SIP Connector receives an INVITE with an SDP offer from the SIP trunk.
- LiveSwitch SIP Connector sends a Trying and a Ringing response to the SIP trunk.
- LiveSwitch SIP Connector sends an OK with an SDP answer to the SIP trunk.
- LiveSwitch SIP Connector receives an empty ACK from the SIP trunk.
Note
The SIP Connector sends the OK with the SDP answer on its own as soon as it resolves the call to an application and a channel. You don't need to send it from a webhook or from your app. For more information on how the SIP Connector resolves a call, see Inbound Call Routing.
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.
Inbound Call Routing
Before the SIP Connector answers an inbound call, it must resolve that call to an Application ID and a Channel ID. It tries the following three mechanisms in order and stops at the first one that supplies both values:
- Routing headers on the INVITE. The
LSAandLSCheaders, or the equivalent SIP URI parameters, set the application and channel directly. For more information, see SIP IVR Routing. - Static inbound mapping. The SIP Connector matches the user part of the To URI against the mappings configured on your application. For more information, see Map Inbound Calls Statically.
- Inbound webhook. The SIP Connector asks your webhook where to route the call. For more information, see Map Inbound Calls Dynamically.
If none of the three supplies both an Application ID and a Channel ID, the SIP Connector rejects the call. You don't have to configure all three. Many deployments use static mapping alone.
The following table describes the response that the caller receives when a call can't be routed:
| Condition | SIP response |
|---|---|
| No routing header, static mapping, or webhook matched the call. | 404 Not Found |
| The inbound webhook didn't respond within 60 seconds. | 480 Temporarily Unavailable |
| The inbound webhook returned 403 Forbidden. | 603 Decline |
| The inbound webhook returned another non-success status code. | 404 Not Found |
The inbound webhook returned a success status code, but the body was missing applicationId or channelId. |
404 Not Found |
Note
The SIP Connector doesn't provide interactive voice response (IVR). It can't play an audio prompt to the caller or collect digits before the call is answered, so your webhook can't ask the caller for input. If you want callers to choose a destination, put an IVR in front of the SIP Connector and have it pass the result using one of the routing models in SIP IVR Routing. After a call is answered and joined to a channel, DTMF tones from the caller are delivered to the other participants in that channel. For more information, see DTMF Signalling.
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.
The SIP Connector matches a mapping by comparing the URI value with the user part of the To URI on the inbound INVITE. Before comparing, it strips any + and - characters from the start and end of both values. Characters in the middle are left alone.
The following table shows how some example values are compared:
| URI value | Compared as | Matches an INVITE to |
|---|---|---|
+18005551212 |
18005551212 |
sip:+18005551212@... or sip:18005551212@... |
18005551212 |
18005551212 |
sip:+18005551212@... or sip:18005551212@... |
1-800-555-1212 |
1-800-555-1212 |
sip:1-800-555-1212@... only |
The first two rows are the same mapping as far as the SIP Connector is concerned, even though they look different in the console. The third is a separate mapping, because the - characters in the middle of the value aren't stripped.
Important
Don't configure two mappings that are equal after stripping, such as +18005551212 and 18005551212. The SIP Connector can't choose between them, and inbound calls to that number fail. Configure one mapping for each phone number or extension.
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
What are Webhooks?
Webhooks are powerful tools that allow real-time communication between LiveSwitch and your external systems. They act as customizable event listeners, automatically sending notifications to your specified web server whenever key actions occur within LiveSwitch. This enables you to seamlessly integrate LiveSwitch events into your own applications and workflows.
Here's how it works:
- You define a webhook by specifying a URL for your server endpoint.
- LiveSwitch monitors for specific events you're interested in.
- When an event occurs, LiveSwitch sends an HTTP POST request to your URL.
- The request body contains detailed event information in JSON format.
- Your server can then process this data and respond accordingly.
With webhooks, you can build responsive, event-driven applications that leverage LiveSwitch's capabilities while seamlessly integrating with your existing infrastructure.
Webhooks are most commonly used to notify customers when a session's recording is ready for download. After a session ends, the system processes the recording by mixing audio and video from all participants into a single file. Once the mixed recording is ready, the system sends a notification via the registered webhook, allowing customers to download the complete recording without manually checking for updates.
You can use a 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 an available agent is found, you create a new meeting room for that agent and map 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 doesn't match any routing header or 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.
LiveSwitch appends the following query string parameters to your webhook URL. Use them to route the call without parsing the SDP or the raw headers:
| Parameter | Description |
|---|---|
| toUser | The user part of the To URI, such as the dialed phone number or extension. |
| fromUser | The user part of the From URI, such as the caller's phone number. |
| toHost | The domain part of the To URI. |
| fromHost | The domain part of the From URI. |
For example, if you configure a Webhook Inbound URL of https://example.com/sip/inbound, a call from +15551112222 to extension 581233 produces the following request URL:
https://example.com/sip/inbound?toUser=581233&fromUser=%2B15551112222&toHost=sip.example.com&fromHost=sip.provider.example.com
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"
}
Your webhook has 60 seconds to respond. The SIP Connector has already sent a Ringing response by the time it calls your webhook, so the caller hears ringing while your webhook works. You can use this window deliberately, for example to hold the call until a host joins the channel, as long as you respond within 60 seconds. If your webhook doesn't respond in time, the SIP Connector sends 480 Temporarily Unavailable to the caller. For the responses that other failures produce, see Inbound Call Routing.
Tip
Also configure a Webhook Inbound Cancel URL if your webhook holds calls open. It tells you when a caller hangs up while your webhook is still deciding, so that you can release any resources you reserved for the call.
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.
LiveSwitch appends the same toUser, fromUser, toHost, and fromHost query string parameters that it appends to the Webhook Inbound URL. Use them to correlate the cancellation with the call your inbound webhook received.
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.
The secret is a value that you create. It isn't issued by your SIP provider or IVR provider, and it's never sent to them. It's a shared secret known only to the SIP Connector and to whatever system builds your inbound calls, so any sufficiently long random string works. Enter it here, and store the same value wherever that system keeps its secrets.
Important
Setting a signature secret makes signing mandatory. Once a secret is configured, the SIP Connector rejects any inbound call that carries routing headers without a valid expiry and signature, and the call then falls through to your static mappings and inbound webhook. Add signing to your IVR at the same time as you set the secret.
Troubleshoot Inbound Calls
Seeing INVITE messages in the SIP Connector logs confirms that your SIP trunk reaches the SIP Connector, but it doesn't confirm that calls are routed. A call that arrives and can't be resolved to an application and a channel is still rejected. To confirm that routing works, configure a static mapping to a known channel, join that channel from your app, and place a test call.
The following table describes the log messages that the SIP Connector writes when an inbound call fails:
| Log message | Cause | Resolution |
|---|---|---|
No map found for caller ... to ... |
No routing header, static mapping, or inbound webhook supplied both an Application ID and a Channel ID. | Add a static mapping for the dialed number, or configure a Webhook Inbound URL. |
SIP webhook took too long to respond. |
The inbound webhook didn't respond within 60 seconds. | Reduce the time your webhook takes to respond. |
Sip webhook returned invalid data. |
The inbound webhook returned a success status code, but the body was missing applicationId or channelId. |
Return both properties as strings. |
Webhook returned unexpected response code: ... |
The inbound webhook returned a non-success status code. | Check your webhook logs for the failing request. |
Received late webhook response for incoming call which has already been canceled. |
The caller hung up before the inbound webhook responded. | No action is required. Configure a Webhook Inbound Cancel URL to be notified when this happens. |
Incoming call requires signature verification, but ... |
The call carried routing headers that failed signature verification. | Confirm that your Signature Secret matches, that the expiry is in the future, and that the server clock is synchronized. For more information, see Request Signatures. |
If routing succeeds using headers, the SIP Connector writes a debug message that begins with LiveSwitch SIP headers are present and verified for call from, followed by the resolved values.