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 a external providers such as Twilio and Telnyx. They will terminate the phone number and route calls to your SIP server.

LiveKit allows you to programmatically configure SIP Trunks to the SIP server. We'll go ahead and add the Trunk that you'd just created.

Create sipTrunk.json file:

{
    "outbound_address": "<my-trunk>.pstn.twilio.com",
    "outbound_number": "+1234567890",
    "outbound_username": "<outbound-user>",
    "outbound_password": "<outbound-pass>",
    "inbound_addresses": [],
    "inbound_numbers_regex": [],
    "inbound_username": "",
    "inbound_password": ""
}

Create SIP Trunk using livekit-cli:

export LIVEKIT_URL=<your LiveKit server URL>
export LIVEKIT_API_KEY=<your API Key>
export LIVEKIT_API_SECRET=<your API Secret>

livekit-cli create-sip-trunk --request sipTrunk.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 sipDispatchRule.json file:

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

Apply the dispatch rule using livekit-cli:

export LIVEKIT_URL=<your LiveKit server URL>
export LIVEKIT_API_KEY=<your API Key>
export LIVEKIT_API_SECRET=<your API Secret>

livekit-cli create-sip-dispatch-rule --request sipDispatchRule.json

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

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.

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:

{
	"sipTrunkId": "<your-trunk-id>",
	"sipCallTo": "<phone-number-to-dial>",
	"roomName": "my-sip-room",
	"participantIdentity": "Test call"
}

Then create the SIP Participant using livekit-cli:

export LIVEKIT_URL=<your LiveKit server URL>
export LIVEKIT_API_KEY=<your API Key>
export LIVEKIT_API_SECRET=<your API Secret>

livekit-cli create-sip-participant --request sipParticipant.json

It should start dialing the phone number specified by sipTrunkId. Once the user picks up, they will be connected to my-sip-room.