Region pinning for telephony

Overview

LiveKit SIP is part of LiveKit Cloud and runs as a globally distributed service, providing redundancy and high availability. By default, SIP endpoints are global, and calls are routed through the region closest to the origination point. Incoming calls are routed to the region closest to the SIP trunking provider's endpoint. Outgoing calls originate from the same region where the CreateSIPParticipant API call is made.

In most cases, using the global endpoint is the recommended approach. However, if you need to exercise more control over call routing — for example, to comply with local telephony regulations — LiveKit SIP supports region pinning. This allows you to restrict both incoming and outgoing calls to a specific region.

Region pinning

Region pinning allows you to restrict calls to a specific region to comply with local telephony regulations. The following sections describe how to enable region pinning for inbound and outbound calls.

Inbound calls

To enable region pinning for incoming calls, configure your SIP trunking provider to use a region-based endpoint. A region-based endpoint is configured to direct traffic only to nodes within a specific region.

Region-based endpoint format

The endpoint format is as follows:

{sip_subdomain}.{region_name}.sip.livekit.cloud

Where:

• {sip_subdomain} is your LiveKit SIP URI subdomain. This is also your project ID without the p_ prefix. You can find your SIP URI on the Project settings  page.

  For example, if your SIP URI is sip:bwwn08a2m4o.sip.livekit.cloud, your SIP subdomain is bwwn08a2m4o.

• {region_name} is one of the following regions:

  aus, eu, india, japan, sa, uk, us

For example to create a SIP endpoint for India, update <your SIP subdomain> in the following string:

<your SIP subdomain>.india.sip.livekit.cloud

For the current list of available regions, see Region-based endpoints for SIP.

Use the region-based endpoint to configure your SIP trunking provider. Follow the instructions for external provider setup in SIP trunk setup.

Outbound calls

To originate calls from the same region as the destination phone number, set the destination_country parameter on your trunk configuration. This works with both inline trunk configuration and stored outbound trunks. When destination_country is set, outbound calls originate from a server within the specified country. If the country code doesn't match any supported region, the parameter has no effect and calls are routed using default behavior.

In the unlikely event that the preferred region is non-operational or offline, calls originate from another region nearby. For the current list of supported regions, see Destination country for outbound calls.

For a full list of parameters for outbound trunks, see CreateSIPOutboundTrunk.

Example: inline trunk with region pinning

Pass destination_country in the inline trunk configuration when creating a SIP participant. The following example sets the destination country to India.

1. Create a file named sip-participant.json with the inline trunk configuration and destination_country set to in:

   {
      "trunk": {
        "hostname": "<SIP server>",
        "auth_username": "<username>",
        "auth_password": "<password>",
        "destination_country": "in"
      },
      "sip_number": "+15105550100",
      "sip_call_to": "<phone-number-to-dial>",
      "room_name": "my-sip-room",
      "participant_identity": "sip-test"
    }

2. Create the SIP participant using the CLI:

   lk sip participant create sip-participant.json

Example: stored outbound trunk with region pinning

You can also set destination_country on a stored outbound trunk to apply region pinning to all calls made through the trunk. The following example creates an outbound trunk that originates calls from India.

1. Create a file named outbound-trunk.json:

   {
     "trunk": {
       "name": "My outbound trunk",
       "phone_number": "+15105550100",
       "username": "myusername",
       "password": "mypassword",
       "destination_country": "in"
     }
   }

2. Create the outbound trunk using the CLI:

   lk sip outbound create outbound-trunk.json

Inbound call fallbacks

Region pinning restricts inbound calls to a single region. If instead you want to keep using the global endpoint but add redundancy, you can configure your SIP trunking provider with fallback endpoints.

By default, inbound calls use your global SIP endpoint, and LiveKit Cloud routes each call to the nearest available region. If a region becomes unavailable, LiveKit Cloud fails over to the next-nearest region automatically, so most applications don't need extra configuration for regional redundancy.

For more control over failover, most SIP trunking providers let you configure multiple endpoints on a single trunk and set the order in which they're tried. You can add one or more region-based endpoints as fallbacks behind your global endpoint. The provider tries the global endpoint first, then fails over to a specific region if the global endpoint doesn't respond.

To configure provider-side fallbacks, follow the instructions for your provider:

• Twilio: Configure inbound fallbacks.
• Telnyx: Configure inbound fallbacks.

Additional resources

The following additional topics provide more information about regions and region pinning.