Introduction
LiveKit SIP bridges the gap between traditional telephony and modern digital communication. It enables seamless interaction between traditional phone systems and LiveKit rooms. You can use LiveKit SIP to accept calls and make calls. When you add LiveKit Agents, you can use an AI voice agent to handle your inbound and outbound calls.
Concepts
LiveKit SIP extends the core primitives — participant, room, and track — to include two additional concepts specific to SIP: trunks and dispatch rules. These concepts are represented by objects created through the API and control how calls are handled.
SIP participant
Each caller, callee, and AI voice agent that participates in a call is a LiveKit participant. A SIP participant is like any other participant and can be managed using the participant APIs. They have the same attributes and metadata as any other participant, and have additional SIP specific attributes.
For inbound calls, a SIP participant is automatically created for each caller. To make an outbound call, you create a SIP participant using the CreateSIPParticipant API to make the call.
Trunks
LiveKit SIP trunks are the bridge between your SIP provider and LiveKit. LiveKit requires a SIP trunk configured with your phone number provider. Configuration settings vary based on your app and whether you're accepting incoming calls or making outgoing calls or both.
An inbound trunk is configured to accept incoming calls and can be limited to specific IP addresses or phone numbers. An outbound trunk is configured for outgoing calls.
The same SIP provider trunk can be associated with both an inbound and an outbound trunk in LiveKit. You only need to create an inbound or outbound trunk once.
Dispatch rules
Dispatch Rules are associated with a specific trunk and control how inbound calls are dispatched to LiveKit rooms. All callers can be placed in the same room or different rooms based on the dispatch rules. Multiple dispatch rules can be associated with the same trunk as long as each rule has a different pin.
Dispatch rules can also be used to add custom participant attributes to SIP participants.
Service architecture
LiveKit SIP relies on the following services:
- SIP trunking provider for your phone number.
- LiveKit server (part of LiveKit Cloud) for API requests, managing and verifying SIP trunks and dispatch rules, and creating participants and rooms for calls (part of LiveKit Cloud).
- LiveKit SIP (part of LiveKit Cloud) to respond to SIP requests, mediate trunk authentication, and match dispatch rules.
If you use LiveKit Cloud, LiveKit SIP is ready to use with your project without any additional configuration. If you're self hosting LiveKit, the SIP service needs to be deployed separately. To learn more about self hosting, see SIP server.
Using LiveKit SIP
The LiveKit SIP SDK is available in multiple languages. To learn more, see SIP API.
LiveKit SIP has been tested with the following SIP providers:
LiveKit SIP is designed to work with all SIP providers. However, compatibility testing is limited to the providers below.
LiveKit SIP supports the following functionality:
| Feature | Description |
|---|---|
| DTMF | You can configure DTMF when making outbound calls by adding them to the CreateSIPParticipant request. To learn more, see Making a call with extension codes (DTMF). |
| SIP REFER | You can transfer calls using the TransferSIPParticipant API. Calls can be transferred to any valid telephone number or SIP URI. To learn more, see Cold transfer. |
| SIP headers | You can map custom X-* SIP headers to participant attributes. For example, custom headers can be used to route calls to different workflows. To learn more, see Custom attributes. |
Next steps
- Learn more about the Inbound call workflow.
- Learn more about the Outbound call workflow.
Use the quickstart guides to create the following: