Create and configure Telnyx SIP trunk

Sign in to LiveKit Cloud

If you're using LiveKit Cloud as your SIP server and you're signed in, your SIP endpoint is automatically included in the code blocks where appropriate.

Creating a Telnyx SIP trunk using the API

Paid account required

Using Telnyx with LiveKit requires a paid Telnyx account. For details on trial account limitations, see Trial account privileges & limitations in the Telnyx developer documentation.

You can use curl command to make calls to the Telnyx API V2. The commands in the steps below use the example phone number, +15105550100. To use the Telnyx console, see Creating a SIP trunk using the Telnyx UI.

Prerequisite

Purchase a Telnyx phone number.

Step 1: Create an environment variable for API key

If you don't have a key a Telnyx API V2 key, see the Telnyx guide to create one.

export TELNYX_API_KEY="<your_api_v2_key>"

Step 2: Create an FQDN connection

The following inbound and outbound commands include the required configuration settings if you plan on using only an inbound or outbound trunk for your LiveKit telephony app. However, by default, an FQDN connection creates both an inbound and outbound trunk.

Creating an FQDN connection. Depending on your use case, select Inbound, Outbound, or Inbound and outbound to accept calls, make calls, or both:

Set the caller's number format to +E.164 for inbound calls (this identifies the caller's number with a leading +):

curl -L 'https://api.telnyx.com/v2/fqdn_connections' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "active": true,
  "anchorsite_override": "Latency",
  "connection_name": "My LiveKit trunk",
  "inbound": {
    "ani_number_format": "+E.164",
    "dnis_number_format": "+e164"
  }
}'

For outbound trunks, complete the following items:

Create a voice profile for outbound calls.
Configure credential authentication with a username and password.

Creating a voice profile:

curl -L 'https://api.telnyx.com/v2/outbound_voice_profiles' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "name": "My LiveKit outbound voice profile",
  "traffic_type": "conversational",
  "service_plan": "global"
}'

Creating an outbound FQDN connection:

curl -L 'https://api.telnyx.com/v2/fqdn_connections' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "active": true,
  "anchorsite_override": "Latency",
  "connection_name": "My LiveKit trunk",
  "user_name": "<username>",
  "password": "<password>",
  "outbound": {
    "outbound_voice_profile_id": "<voice_profile_id>"
  }
}'

To configure an FQDN trunk for both inbound and outbound calls:

Create a voice profile for outbound calls.
Set the caller's number format to +E.164.
Configure credential authentication with a username and password.

Create a voice profile

curl -L 'https://api.telnyx.com/v2/outbound_voice_profiles' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "name": "My LiveKit outbound voice profile",
  "traffic_type": "conversational",
  "service_plan": "global"
}'

Create an inbound and outbound FQDN connection

curl -L 'https://api.telnyx.com/v2/fqdn_connections' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "active": true,
  "anchorsite_override": "Latency",
  "connection_name": "My LiveKit trunk",
  "user_name": "<username>",
  "password": "<password>",
  "inbound": {
    "ani_number_format": "+E.164",
    "dnis_number_format": "+e164"
  },
  "outbound": {
    "outbound_voice_profile_id": "<voice_profile_id>"
  }
}'

Copy the FQDN connection ID from the output:

{
  "data": {
    "id":"<connection_id>",
    ...
  }
}

Create an FQDN with your LiveKit SIP endpoint and your FQDN connection ID:

curl -L 'https://api.telnyx.com/v2/fqdns' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "connection_id": "<connection_id>",
  "fqdn": "<your SIP endpoint>",
  "port": 5060,
  "dns_record_type": "a"
}'

Region-based endpoints

To restrict calls to a specific region, replace your global LiveKit SIP endpoint with a region-based endpoint.

Step 3: Associate phone number and trunk

Get the phone number ID for phone number 5105550100:

curl -L -g 'https://api.telnyx.com/v2/phone_numbers?filter[phone_number]=5105550100' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY"

Copy the phone number ID from the output:

{
  "meta": {
    "total_pages": 1,
    "total_results": 1,
    "page_number": 1,
    "page_size": 100
  },
  "data": [
    {
      "id": "<phone_number_id>",
      ...
    }
  ]
}

Add the FQDN connection to the phone number:

curl -L -X PATCH 'https://api.telnyx.com/v2/phone_numbers/<phone_number_id>' \
-H 'Content-Type: application/json' \
-H 'Accept: application/json' \
-H "Authorization: Bearer $TELNYX_API_KEY" \
-d '{
  "id": "<phone_number_id>",
  "connection_id": "<connection_id>"
}'

Step 4: Set custom headers in SIP INVITE

This step ensures outbound calls from LiveKit to Telnyx are properly authenticated.

Telnyx uses SIP digest authentication:

LiveKit sends an INVITE to Telnyx with the username.
Telnyx responds with a 407 Proxy Authentication Required and an encryption key.
LiveKit sends a second INVITE with the username and encrypted password.
Telnyx validates the username and decrypted password to authenticate the request.

To make this work reliably, LiveKit must include the username in the first INVITE message as a custom SIP header.

By default, LiveKit doesn't include the username in the initial INVITE. When this happens, Telnyx normally returns a 407 Proxy Authentication Required response. However, if Telnyx finds any existing SIP IP connection from the same source IP, it uses that connection as the authenticated user and skips the 407. Because this lookup is based only on the source IP, the matched connection could belong to a different customer.

Configuring LiveKit to send the username in the first INVITE ensures Telnyx always replies with a 407 challenge to initiate SIP digest authentication.

To include a custom SIP header in INVITE messages, use the headers_to_attributes field for your outbound trunk. Add the key X-Telnyx-Username to the mapping with your username as the value:

{
  "trunk": {
    "name": "My outbound trunk",
    "address": "sip.telnyx.com",
    "numbers": ["+15555555555"],
    "authUsername": "<username>",
    "authPassword": "<password>",

    "headers_to_attributes": {
      "X-Telnyx-Username": "<username>"
    }
  }
}

Creating a SIP trunk using the Telnyx UI

Optionally, you can also create the Telnyx SIP trunk using the Telnyx Portal UI:

Sign in to the Telnyx portal.
Purchase a phone number.
Navigate to Real-time Communications » Voice » SIP Trunking.
Select Create SIP connection:
- Enter a descriptive name for your SIP trunk.
- Select FQDN → select Next.
- Select + Add FQDN and enter your LiveKit SIP endpoint into the FQDN field and save.
  For example, vjnxecm0tjk.sip.livekit.cloud.
  Region-based endpoints
  To restrict calls to a specific region, replace your global LiveKit SIP endpoint with a region-based endpoint.
- In the Outbound calls authentication section, complete the Username and Password fields.
- Select Next.
- Select Next on the following page to skip the Configuration section.
- On the Inbound settings page, complete the following settings:
  - For Destination number format, select +E.164.
  - For Origination number format, select +E.164.
  - For SIP transport protocol, select either TCP or UDP.
  - For SIP region, select your region.
  - Select Next.
- On the Outbound settings page, select a profile for the Outbound voice profile field.
  If you don't have a profile, create one by navigating to Real-Time Communications » Voice » Settings and select Create Profile.
- Select Next.
- Select a phone number to associate with the SIP trunk by selecting the link icon.
- Select Complete.

Configure HD voice

Telnyx supports HD voice for customers in the US. To enable HD voice, configure the following settings in the Telnyx portal:

Enable HD voice for a phone number

You must enable HD voice for the phone number before you can use it with HD voice:

Sign in to the Telnyx portal.
Navigate to Real-Time Communications » Numbers » Manage Numbers.
Select the edit icon for the phone number you are want to use.
Select the Voice tab and navigate to the Services section. Select Enable HD Voice.
Save your changes.

Enable codecs for the SIP trunk

You must enable the G.722 codec for the SIP trunk associated with the phone number from the previous step:

Navigate to Real-Time Communications » Voice » SIP Trunking.
Select the edit icon for the SIP trunk associated with the phone number.
Select the Inbound tab.
In the Codecs list, select G.722. Leave G.711U selected for compatibility.
Save your changes.

Next steps

Head back to the main setup documentation to finish connecting your SIP trunk to LiveKit.

SIP trunk setup

Configure your Telnyx trunk in LiveKit.