Telnyx & LiveKit: SIP Trunk Configuration

This configuration guide is designed to help you establish and optimize a SIP Trunk between Telnyx, a global leader in VoIP communications, and LiveKit, a robust platform for building real-time audio and video applications.

The primary objective of this document is to provide a comprehensive, step-by-step approach for configuring your SIP Trunk setup. This guide caters to both beginners and experienced professionals, ensuring that all readers can effectively integrate these two powerful services. By the end of this guide, you will be able to:

**1. Set Up Telnyx: ** Configure your Telnyx account and SIP Trunk settings to prepare for integration.

2. Configure LiveKit: Adjust your LiveKit settings to accept and manage Telnyx SIP Trunk communications.

3. Debug and Optimize: Troubleshoot common issues and fine-tune your configuration for optimal performance.

Follow the steps below to create a SIP connection to your LiveKit account.

Your checklist:

• 1. Have an account created on Telnyx portal
• 2. Complete L2 verification process
• 3. Purchase a number to be used for the voice calls

• In the Telnyx Mission Control Portal choose a “Real-Time Communications” -> “Voice” -> “SIP Trunking” menu on the left sidebar
• Click “Add SIP Connection” button

• Provide a name for your new SIP Connection
• Select FQDN as a type of connection
• Create a sip connection

• Choose “FQDN” as a connection type
• Provide SIP URI obtained from your LiveKit account. You can find it in your project settings page.
• Save FQDN settings with “Add” button

• Switch to the “Outbound Calls Authentication” tab in the Authentication & Routing Configuration section
• Choose “Credentials” for the Authentication Method
• Provide your user name and password which will be used later for the LiveKit outbound trunk configuration

• On top of SIP Connection page switch to the Outbound tab
• Select an existing Outbound Voice Profile from a dropdown list.
• If no profile is available you can create a one with a “Create New Outbound Voice Profile” link

• Finally save your sip connection with a “Save” button at the bottom of the page

Integration over SIP trunk with LiveKit allows also to redirect voice calls originated from LiveKit to Telnyx Voice AP applicationsI. With that option you can implement advanced voice applications with the features like listed below:

• Call recording
• IVR (Interactive Voice Response)
• TTS (Text-To-Speech)
• STT (Speech-To-Text / Call transcription)
• Conversational AI (Voice bots with different AI models)
• and many more

To configure the voice application:

• Switch to a “Real-Time Communications” -> “Voice” -> “Programmable Voice” menu on the left sidebar
• Create a new application with an “Add New App” button
• Provide a name for your application
• Configure webhooks URL to receive webhooks about call status changes

• In the Inbound section provide a subdomain name (later you need to use it in a LiveKit outbound trunk setup)
• In the Outbound section select an outbound voice profile
• Save the voice app configuration

• Switch to a “Real-Time Communications” -> “Voice” -> “Outbound Voice Profile” menu on the left sidebar
• Add a new Profile and provide a name for it
• Or you can adjust the existing profile with clicking on the edit icon

• Select the destinations which should be allowed to make outbound calls to
• Click “Save” button to confirm your configuration

• Switch to a “Real-Time Communications” -> “Voice” -> “My Numbers” menu on the left sidebar
• For the number(s) you would like to use for the LiveKit voice participants, select your LiveKit sip connection from a dropdown list presented in the “SIP connections” column
• Update your configuration with a “Save” button
• You can purchase additional numbers in a “Buy Numbers” menu
• The same SIP connection may be assigned to multiple numbers

Follow the steps below to configure a SIP trunk for your LiveKit account.

Your checklist:

• 1. SIP URI is available in your project settings
• 2. LiveKit CLI is installed on your computer
• 3. ENV variables have been configured

Please refer to LiveKit Quick Start page for detailed SIP configuration instructions

• Create a json file (inboundTrunk.json) with the configuration of your inbound sip trunk
• Provide a name for your trunk and a number to be used (or an array of the comma delimited numbers)

{
   "trunk": {
       "name": "Demo Inbound Trunk",
       "numbers": ["1234567890"]
   }
}

• Run LiveKit CLI command to create an inbound trunk

lk sip inbound create inboundTrunk.json

• In the response you will receive a trunk ID

SIPTrunkID: <your-trunk-id>

• Create a json file (dispatchRule.json)
• Provide a name for your rule, a trunk ID from the previous step and room name to which incoming calls should be connected

{
   "name": "Demo Dispatch Rule",
   "trunk_ids": ["<your-trunk-id>"],
   "rule": {
       "dispatchRuleDirect": {
           "roomName": "my-sip-room",
           "pin": ""
       }
   }
}

• Run LiveKit CLI command to create a dispatch rule

lk sip dispatch create dispatchRule.json

• Create a json file (outboundTrunk.json) with the configuration of your outbound sip trunk
• Provide a name for your trunk
• In the address parameter provide “sip.telnyx.com” if you configured a SIP connection on Telnyx side
• If you want to make calls to the configured Voice App, for the address parameter provide a subdomain configured in the Inbound section of your voice application
• Provide username and password you set in your sip trunk configuration for the Outbound Calls Authentication.
• Credentials should be left blank when connecting to the subdomain of your Voice App.

{
   "trunk": {
       "name": "Demo Outbound Trunk",
       "address": "sip.telnyx.com",
       "numbers": ["1234567890"],
       "auth_username": "<outbound-user>",
       "auth_password": "<outbound-pass>"
   }
}

• Run LiveKit CLI command to create an outbound trunk

lk sip outbound create outboundTrunk.json

• In the response you will receive a trunk ID

SIPTrunkID: <your-trunk-id>

• To test an outbound call you can initiate a call with a CLI command
• Create a json file (sipParticipant.json) providing outbound trunk ID obtained in the previous step
• Provide a number to be called in a sip_call_to parameter
• Provide a room name, participant identity and name

{
	"sip_trunk_id": "<your-trunk-id>",
	"sip_call_to": "<phone-number-to-dial>",
	"room_name": "my-sip-room",
	"participant_identity": "sip-test",
	"participant_name": "Test Call"
}

• Run LiveKit CLI command to make an outbound call

lk sip participant create sipParticipant.json

In Telnyx Mission Control Portal we are providing debugging tools where you can troubleshoot any issues with your SIP trunk communication checking SIP call flows, QoS stats and communication to a defined webhooks.

• Go to the “Debugging” menu under “Reporting” in the left menu
• Select “SIP Call Flow Tool” on the top bar
• Specify your search criteria and press “Search CDRs” button
• From the list of listed calls select a one with “Call Data Debugging” button

Now you can review SIP call flow with all detailed data for each of the SIP request

You can also check “Session Info” on the next tab or export PCAP data on the “Export” tab.

• 1. Telnyx SIP trunk configuration data - https://sip.telnyx.com
• 2. Telnyx SIP trunk setup - https://developers.telnyx.com/docs/voice/sip-trunking/get-started
• 3. LiveKit SIP configuration - https://docs.livekit.io/sip/