Skip to main content

SIP outbound trunk

How to create and configure a outbound trunk to make outgoing calls.

To provision an outbound trunk with the SIP Service, use the CreateSIPOutboundTrunk API. It returns an SIPOutboundTrunkInfo object that describes the created SIP trunk. You can query these parameters any time using the ListSIPOutboundTrunk API.

Restricting calls to a region

To originate calls from the same region as the destination phone number, set the destination_country parameter for an outbound trunk. This applies region pinning to all calls made through the trunk. When destination_country is enabled, outbound calls are routed based on location:

  • For countries that LiveKit operates data centers in, calls originate from a server within the country.
  • For other countries, calls originate from a server that is closest to that country.

In the unlikely event that the preferred region is non-operational or offline, calls originate from another region nearby. For a full list of supported regions, see Available regions.

The destination_country parameter accepts a two-letter country code. To learn more, see CreateSIPOutboundTrunk.

Create an outbound trunk

The following creates a SIP outbound trunk with username and password authentication. It makes outbound calls from number +15105550100.

  1. Create a file named outbound-trunk.json using your phone number, trunk domain name, and username and password:

    {
    "trunk": {
    "name": "My outbound trunk",
    "address": "<my-trunk>.pstn.twilio.com",
    "numbers": ["+15105550100"],
    "authUsername": "<username>",
    "authPassword": "<password>"
    }
    }
  2. Create the outbound trunk using the CLI:

    lk sip outbound create outbound-trunk.json

    The output of the command returns the trunk ID. Copy it for the next step:

    SIPTrunkID: <your-trunk-id>

Configuring an outbound trunk for any phone number

The numbers parameter for outbound trunks is a required field. However, you can set the parameter to any string (for example, *) to use the outbound trunk for calls from any number. This is useful if you want to use the same outbound trunk for all calls or if you want to use a different phone number for each call.

Instead of setting the number on the trunk, you can set the phone number to call from using the sip_number parameter for the CreateSIPParticipant API.

The following example creates an outbound trunk that allows calling from any number, then initiates a call using the outbound trunk.

  1. Create an outbound trunk using the CLI.

    Create a file named outbound-trunk.json and copy and paste the following content:

    {
    "trunk": {
    "name": "My outbound trunk",
    "address": "<my-trunk>.pstn.twilio.com",
    "numbers": ["*"],
    "auth_username": "<username>",
    "auth_password": "<password>"
    }
    }

    Create the outbound trunk using the CLI:

    lk sip outbound create outbound-trunk.json
  2. Initiate a call from the number +15105550100 using the CLI. This number is the phone number configured with your SIP trunk provider. Use the <trunk-id> from the output of the previous step.

    Create a file named participant.json and copy and paste the following content:

    {
    "sip_number": "+15105550100",
    "sip_trunk_id": "<trunk-id>",
    "sip_call_to": "+12135550100",
    "room_name": "open-room",
    "participant_identity": "sip-test",
    "participant_name": "Test call participant",
    "wait_until_answered": true
    }
    Important

    If you're using Telnyx, the leading + in the phone number assumes the Destination Number Format is set to +E.164 for your number.

    Initiate the call using the CLI:

    lk sip participant create participant.json

    After you run the command, a call from the number +15105550100 to +12135550100 is initiated. Output from the command returns when the call is answered.

List outbound trunks

Use the ListSIPOutboundTrunk API to list all outbound trunks and trunk parameters.

lk sip outbound list

Update an outbound trunk

The UpdateSIPOutboundTrunk API allows you to update specific fields of an outbound trunk or replace an outbound trunk with a new one.

Update specific fields of an outbound trunk

The UpdateSIPOutboundTrunkFields API allows you to update specific fields of an outbound trunk without affecting other fields.

  1. Create a file named outbound-trunk.json with the fields you want to update. The following example updates the name and phone numbers for the trunk:

    {
    "name": "My updated outbound trunk",
    "address": "<my-trunk>.pstn.twilio.com",
    "numbers": ["+15105550100"]
    }
  2. Update the outbound trunk using the CLI:

    lk sip outbound update --id <sip-trunk-id> outbound-trunk.json

    The output of the command returns the trunk ID:

    SIPTrunkID: <your-trunk-id>

Replace an outbound trunk

The UpdateSIPOutboundTrunk API allows you to replace an existing outbound trunk with a new one using the same trunk ID.

The CLI doesn't support replacing outbound trunks.

IP address range for LiveKit Cloud SIP

LiveKit Cloud nodes do not have a static IP address range, thus there's no way currently to use IP range for outbound authentication.

Thus, prefer setting user/password authentication on SIP trunk Provider.

If it's unavailable, or IP range is required in addition to user/password, set range(s) that include all IPs: e.g. 0.0.0.0/0 or 0.0.0.0/1+128.0.0.0/1.