SIP Quickstart

You'll need the following for this quickstart:

• 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

sip:<your SIP host>

SIP Trunks are provided by external providers such as Twilio and Telnyx. They terminate phone numbers and route calls to your SIP server.

Once configured, a single SIP Trunk can route both incoming and outgoing calls.

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>

To enable incoming calls from a phone number to LiveKit, you'll need to set up an Inbound Trunk and a Dispatch Rule.

An Inbound Trunk instructs LiveKit to accept calls to one or more numbers that you own. Create a file inboundTrunk.json with the following content (assuming +1234567890 is the number that you own):

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

Create SIP Inbound Trunk using lk:

lk sip inbound create inboundTrunk.json

It will print the Trunk ID:

SIPTrunkID: <your-trunk-id>

Dispatch Rules are used to route inbound SIP calls into LiveKit rooms. In this guide, we'll dispatch all callers into a specific room named my-sip-room.

Create dispatchRule.json file:

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

Apply the dispatch rule using lk:

lk sip dispatch create dispatchRule.json

Multiple Dispatch rules can be created for the same Trunk as long as their pins are different.

{
    "name": "Demo Dispatch Rule",
    "trunk_ids": ["<your-trunk-id>"],
    "rule": {
        "dispatchRuleIndividual": {
            "roomPrefix": "call-"
        }
    }
}

Assuming +1234567890 phone number was acquired, calling this number should place you into my-sip-room.

You can talk to the caller by joining the room from our example app.

To make outgoing calls, an Outbound Trunk needs to be configured. SIP trunking providers typically require authentication when accepting outbound SIP requests. Use the previously configured credentials from earlier in the example outboundTrunk.json below:

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

Create Outbound Trunk using lk:

lk sip outbound create outboundTrunk.json

It will print the Trunk ID:

SIPTrunkID: <your-trunk-id>

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.