Log in to see your real credentials populated in many places throughout this page
Pre-requisites
- Phone number on one of the SIP trunk providers (like Twilio or Telnyx)
- LiveKit Cloud project or a self-hosted instance of LiveKit server
- LiveKit CLI
Preparing SIP server
SIP is provisioned with every LiveKit Cloud project. If you are signed in to LiveKit Cloud, your SIP server URI is:
sip:<your SIP host>
Copy this URI as it will be used to configure your SIP trunk provider.
Create a SIP trunk
SIP Trunks are provided by external providers such as Twilio and Telnyx. They terminate phone numbers and route calls to your LiveKit SIP server.
Once configured, a single SIP Trunk can route both incoming and outgoing calls.
- Buy a phone number. This guide will assume
+1234567890
. - Follow the SIP Quickstart tutorial.
- For inbound calling:
- Choose FQDN Authentication
- Enter your SIP URI from above into the FQDN field
- In the
Inbound
tab, ensureDestination Number Format
is set to+E.164
- You can use either UDP or TCP for
SIP Transport Protocol
- For outbound calling:
- Select SIP Signaling Address for your region
- Configure Credentials Authentication
- Be sure to create an
Outbound Voice Profile
and selected under the SIP Connection
- Go to
Numbers
tab and assign the purchased number to the SIP trunk
Configuring LiveKit CLI
LiveKit CLI (lk
command) should be configured to use your LiveKit Cloud or self-hosted instance. You can do so using environment variables
export LIVEKIT_URL=<your LiveKit server URL>export LIVEKIT_API_KEY=<your API Key>export LIVEKIT_API_SECRET=<your API Secret>
Incoming calls
If you're only interested in outgoing calls, you can skip to the Outgoing Calls section.
To enable incoming calls from a phone number to LiveKit, you'll need to set up both an Inbound Trunk and a Dispatch Rule on the LiveKit side.
Create inbound LiveKit trunk
An Inbound LiveKit Trunk instructs LiveKit to accept calls to one or more numbers that you own. Create a file inboundLiveKitTrunk.json
with the following content (assuming +1234567890
is the number that you own):
{"trunk": {"name": "Demo Inbound LiveKit Trunk","numbers": ["+1234567890"]}}
Note, this assumes you have configured Destination Number Format
to +E.164
in Telnyx.
Create SIP Inbound LiveKit Trunk using lk
:
lk sip inbound create inboundLiveKitTrunk.json
It will print the LiveKit Trunk ID:
SIPTrunkID: <your-livekit-trunk-id>
Add dispatch rule
Dispatch Rules are used to route inbound SIP calls into LiveKit rooms. In this guide, we'll dispatch callers into individual rooms prefixed with call-
.
Create dispatchRule.json
file:
{"name": "Demo Dispatch Rule","trunk_ids": ["<your-livekit-trunk-id>"],"rule": {"dispatchRuleIndividual": {"roomPrefix": "call-"}}}
Apply the dispatch rule using lk
:
lk sip dispatch create dispatchRule.json
Multiple Dispatch rules can be created for the same LiveKit Trunk as long as their pins are different.
dispatchRuleIndividual
places callers into individual rooms prefixed with call-_<number>_<random_suffix>
. If you are trying to route every caller into the same room, use dispatchRuleDirect
. In this case, we route every caller to my-sip-room
:
{"name": "Demo Dispatch Rule","trunk_ids": ["<your-livekit-trunk-id>"],"rule": {"dispatchRuleDirect": {"roomName": "my-sip-room","pin": ""}}}
Testing incoming calls
Assuming +1234567890
phone number was acquired, calling this number should place you into a room prefixed with call-
, e.g. call-_+1234567890_<random_suffix>
.
You can talk to the caller by joining the room from our example app using your LiveKit server URL and an access token.
For example, to generate an access token to join the room my-sip-room
with the username test-user
, run the following command:
lk token create \--api-key <your API Key> \--api-secret <your API Secret> \--join --room my-sip-room \--identity test-user \--valid-for 24h
Outgoing calls
If you want to answer incoming calls, ensure you've completed the Incoming Calls section.
Add outbound trunk
To make outgoing calls, the provider's Outbound Trunk needs to be registered with LiveKit. SIP trunking providers typically require authentication when accepting outbound SIP requests so that they can make sure nobody else is making calls with your number. Use the previously configured credentials from earlier in the example outboundTrunk.json
below:
{"trunk": {"name": "Demo Outbound Trunk","address": "sip.telnyx.com","numbers": ["+1234567890"],"auth_username": "<outbound-username>","auth_password": "<outbound-password>"}}
Use a regional SIP Signaling Address from Telnyx SIP Signaling Addresses.
Telnyx numbers must omit the leading +
by default.
Create Outbound Trunk using lk
:
lk sip outbound create outboundTrunk.json
It will print the Trunk ID:
SIPTrunkID: <your-trunk-id>
Testing outgoing calls
You may also dial phone numbers and connect them to LiveKit rooms. Let's try connecting your phone number to my-sip-room
.
Create sipParticipant.json
file:
{"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"}
Then create the SIP Participant using lk
:
lk sip participant create sipParticipant.json
It should use the phone number specified by sip_trunk_id
Trunk and dial sip_call_to
number. Once the user picks up, they will be connected to my-sip-room
.
You can talk to the dialed phone number by joining the room from our example app.