Receive an Inbound SIP Call

You can let callers dial a phone number and join a LiveSwitch channel, so that people on a phone and people in your app share the same conference. The SIP Connector accepts the inbound call from your SIP trunk and joins it to a channel.

Note

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

Before You Begin

Make sure that you have the following:

  • An installed and configured SIP Connector, including a SIP trunk that supports sending early offers.
  • A phone number from your SIP provider, routed to your SIP Connector.
  • An application in the LiveSwitch Console that your app connects to.

Route All Calls to One Channel

Start with a static mapping that sends every call to a single channel. This confirms that signaling, media, and routing all work before you add any logic of your own.

  1. In the LiveSwitch Console > Applications > SIP Inbound Mapping Configuration section, click NEW to add a new mapping.
  2. In the URI field, enter your phone number.
  3. In the Channel field, enter a channel ID, such as test-channel.
  4. Join the same channel from your app.
  5. Call your phone number.

The call connects and audio flows in both directions. If it doesn't, see Troubleshoot Inbound Calls.

Note

INVITE messages in the SIP Connector logs confirm that your trunk reaches the SIP Connector. They don't confirm that a call was routed. A call that can't be resolved to a channel is rejected with 404 Not Found even though the INVITE arrived.

Route Calls to Different Channels

Once a single channel works, choose how to send callers to different channels. The following approaches are available, and you can combine them:

Approach Use when
One static mapping for each number You have a small, fixed set of destinations and can buy a number for each.
Routing headers set by an IVR An IVR answers first and knows the destination. For more information, see SIP IVR Routing.
Inbound webhook Your app decides the destination at call time, such as looking up a meeting code or finding an available agent.

Choose a Channel Using a Webhook

Configure a Webhook Inbound URL in the LiveSwitch Console > Deployments > SIP Configuration section. When a call doesn't match a routing header or a static mapping, the SIP Connector sends an HTTP POST request to your webhook and uses the response to route the call.

The SIP Connector appends the dialed number and the caller's number to your webhook URL as query string parameters, so you can route on them without parsing the SDP:

https://example.com/sip/inbound?toUser=581233&fromUser=%2B15551112222&toHost=sip.example.com&fromHost=sip.provider.example.com

Respond with the application and channel to join:

{
  "applicationId": "my-app",
  "channelId": "meeting-581233",
  "userId": "+15551112222"
}

Setting userId is worth doing. It's the identity that the other participants in the channel see, and it defaults to the full From URI, which is less readable than a phone number.

For the full request and response format, see Map Inbound Calls Dynamically.

Prompt Callers for a Meeting Code

The SIP Connector can't prompt callers. It has no interactive voice response (IVR), so it can't play audio or collect digits before the call is answered, and your inbound webhook has no way to ask the caller a question.

To collect a meeting code, put an IVR in front of the SIP Connector. The IVR answers the call, plays the prompt, collects the digits, and then passes the result to the SIP Connector.

A typical flow looks like the following:

  1. The caller dials your number, which is routed to your IVR rather than directly to your SIP trunk.
  2. The IVR answers and prompts the caller for a meeting code.
  3. The IVR connects the call to your SIP Connector, carrying the code either in the SIP URI or in a routing header.
  4. The SIP Connector resolves the call, either from the routing headers or by calling your inbound webhook with the code in toUser.

For the third step, put the collected digits in the user part of the SIP URI that your IVR connects to. The syntax varies by provider, so consult your provider's documentation.

Pseudo-code IVR control block:

<Connect sip="sip:581233@my-sip-connector.xyz" />

Your inbound webhook then receives toUser=581233, validates the code, and returns the matching channel.

Note

Not every provider can do this. Some SIP trunking products connect inbound calls straight to your origination address with no opportunity to answer, prompt, or add routing information. If yours behaves that way, see whether the provider offers a separate programmable voice product that does.

To set the destination in the IVR instead of in a webhook, use routing headers. For the header names, the URI parameter equivalents, and how to sign the request, see SIP IVR Routing.

Important

Expose the SIP Connector through your firewall if your IVR connects to it directly. Restrict inbound traffic on your SIP port to the known IP ranges of your IVR provider, and set a Signature Secret so that the SIP Connector accepts routing headers only from your IVR.

Handle Callers Who Arrive First

A caller who joins an empty channel hears silence until someone else joins. Two options avoid this:

  • Hold the caller upstream. Keep the call in your IVR, playing an announcement or hold music, and connect it to the SIP Connector only once someone is in the channel. The caller can wait indefinitely, and you control what they hear.
  • Hold the webhook response. Your inbound webhook has 60 seconds to respond, and the caller hears ringing during that time. Delay your response until a host joins the channel, then return the channel to join.

Holding the webhook response is simpler, but the 60-second limit applies. If your webhook doesn't respond in time, the caller receives 480 Temporarily Unavailable. Also configure a Webhook Inbound Cancel URL so that you're notified when a caller hangs up while waiting.

Next Steps

  • Collect digits from callers after the call connects, such as for in-call menus. For more information, see DTMF Signalling.
  • Add callers to an existing conference from your app. For more information, see Make an Outbound SIP Call.