SIP APIs

Use LiveKit's built-in SIP APIs to manage your SIP-based apps.

Overview

LiveKit has built-in APIs that let you to manage SIP trunks, dispatch rules, and SIP participants. The SIP API is available with LiveKit server SDKs and CLI:

important

Requests to the SIP API require the SIP admin permission unless otherwise noted. To create a token with the appropriate grant, see SIP grant.

To learn more about additional APIs, see Server APIs.

Using endpoints

The SIP API is accessible via /twirp/livekit.SIP/<MethodName>. For example, if you're using LiveKit Cloud the following URL is for the CreateSIPInboundTrunk API endpoint:

https://<your LiveKit URL domain>/twirp/livekit.SIP/CreateSIPInboundTrunk

Authorization header

All endpoints require a signed access token. This token should be set via HTTP header:

Authorization: Bearer <token>

LiveKit server SDKs automatically include the above header.

Post body

Twirp expects an HTTP POST request. The body of the request must be a JSON object (application/json) containing parameters specific to that request. Use an empty {} body for requests that don't require parameters.

Examples

For example, create an inbound trunk using CreateSIPInboundTrunk:

curl -X POST https://<your LiveKit URL domain>/twirp/livekit.SIP/CreateSIPInboundTrunk \
-H "Authorization: Bearer <token-with-sip-admin>" \
-H 'Content-Type: application/json' \
-d '{ "name": "My trunk", "numbers": ["+15105550100"] }'

List inbound trunks using ListSIPInboundTrunk API endpoint to list inbound trunks:

curl -X POST https://<your LiveKit URL domain>/twirp/livekit.SIP/ListSIPInboundTrunk \
-H "Authorization: Bearer <token-with-sip-admin>" \
-H 'Content-Type: application/json' \
-d '{}'

SIPService APIs

The SIPService APIs allow you to manage trunks, dispatch rules, and SIP participants.

tip

All RPC definitions and options can be found here.

CreateSIPInboundTrunk

Create an inbound trunk with the specified settings.

Returns SIPInboundTrunkInfo.

ParameterTypeRequiredDescription
namestringyesname of the trunk.
metadatastringInitial metadata to assign to the trunk. This metadata is added to every SIP participant that uses the trunk.
numbersarray<string>yesArray of provider phone numbers associated with the trunk.
allowed_addressesarray<string>List of IP addresses that are allowed to use the trunk. Each item in the list can be an individual IP address or a Classless Inter-Domain Routing notation representing a CIDR block.
allowed_numbersarray<string>List of phone numbers that are allowed to use the trunk.
auth_usernamestringIf configured, the username for authorized use of the provider's SIP trunk.
auth_passwordstringIf configured, the password for authorized use of the provider's SIP trunk.
headersmap<string, string>SIP X-* headers for INVITE request. These headers are sent as-is and may help identify this call as coming from LiveKit for the other SIP endpoint.
headers_to_attributesmap<string, string>Key-value mapping of SIP X-* header names to participant attribute names.
ringing_timeoutgoogle.protobuf.DurationMaximum time for the call to ring.
max_call_durationgoogle.protobuf.DurationMaximum call duration.
krisp_enabledboolTrue to enable voice isolation.

CreateSIPOutboundTrunk

Create an outbound trunk with the specified settings.

Returns SIPOutboundTrunkInfo.

ParameterTypeRequiredDescription
namestringyesname of the trunk.
metadatastringUser-defined metadata for the trunk. This metadata is added to every SIP participant that uses the trunk.
addressstringyesHostname or IP the SIP INVITE is sent to. This is not a SIP URI and shouldn't contain the sip: protocol.
numbersarray<string>yesList of provider phone numbers associated with the trunk.
transportSIPTransportSIP transport protocol used for outbound call.
numbersarray<string>List of phone numbers that are allowed to use the trunk.
auth_usernamestringIf configured, the username for authorized use of the provider's SIP trunk.
auth_passwordstringIf configured, the password for authorized use of the provider's SIP trunk.
headersmap<string, string>SIP X-* headers for INVITE request. These headers are sent as-is and may help identify this call as coming from LiveKit for the other SIP endpoint.
headers_to_attributesmap<string, string>Key-value mapping of SIP X-* header names to participant attribute names.

CreateSIPDispatchRule

Create dispatch rule.

Returns SIPDispatchRuleInfo.

ParameterTypeRequiredDescription
ruleSIPDispatchRuleyesType of dispatch rule.
trunk_idsarray<string>List of associated trunk IDs. If empty, all trunks match this dispatch rule.
inbound_numbersarray<string>If set, the dispatch rule only accepts calls made to numbers in the list.
namestringyesHuman-readable name for the dispatch rule.
metadatastringOptional metadata for the dispatch rule. If defined, participants created by the rule inherit this metadata.
attributesmap<string, string>Key-value mapping of user-defined attributes. Participants created by this rule inherit these attributes.

CreateSIPParticipant

note

Requires SIP call grant on authorization token.

Create a SIP participant to make outgoing calls.

Returns SIPParticipantInfo

ParameterTypeRequiredDescription
sip_trunk_idstringyesID for SIP trunk used to dial user.
sip_call_tostringyesPhone number to call.
sip_numberstringSIP number to call from. If empty, use trunk number.
room_namestringyesName of the room to connect the participant to.
participant_identitystringIdentity of the participant.
participant_namestringName of the participant.
participant_metadatastringUser-defined metadata that is attached to created participant.
participant_attributesmap<string, string>Key-value mapping of user-defined attributes to attach to created participant.
dtmfstringDTMF digits (extension codes) to use when making the call. Use character w to add a 0.5 second delay.
play_dialtoneboolOptionally play dial tone in the room in the room as an audible indicator for existing participants.
hide_phone_numberboolIf true, use a random value for participant identity and phone number ommitted from attributes. By default, the participant identity is created using the phone number (if the participant identity isn't explicitly set).
ringing_timeoutgoogle.protobuf.DurationMaximum time for the callee to answer the call.
max_call_durationgoogle.protobuf.DurationMaximum call duration.
enable_krispboolTrue to enable voice isolation for the callee.

DeleteSIPDispatchRule

Delete a dispatch rule.

Returns SIPDispatchRuleInfo.

ParameterTypeRequiredDescription
sip_dispatch_rule_idstringID of dispatch rule.

DeleteSIPTrunk

Delete a trunk.

Returns SIPTrunkInfo.

ParameterTypeRequiredDescription
sip_trunk_idstringyesID of trunk.

GetSIPInboundTrunk

Get inbound trunk.

Returns GetSIPInboundTrunkResponse.

ParameterTypeRequiredDescription
sip_trunk_idstringyesID of trunk.

GetSIPOutboundTrunk

Get outbound trunk.

Returns GetSIPOutboundTrunkResponse.

ParameterTypeRequiredDescription
sip_trunk_idstringyesID of trunk.

ListSIPDispatchRule

List dispatch rules.

Returns array<SIPDispatchRuleInfo>.

ListSIPInboundTrunk

List inbound trunks.

Returns array<SIPInboundTrunkInfo>.

ListSIPOutboundTrunk

List outbound trunks.

Returns array<SIPOutboundTrunkInfo>.

TransferSIPParticipant

note

Requires SIP call grant on authorization token.

Transfer call to another number or SIP endpoint.

Returns google.protobuf.Empty.

ParameterTypeRequiredDescription
participant_identitystringyesIdentity of the participant to transfer.
room_namestringyesName of the room the participant is currently in.
transfer_tostringyesPhone number or SIP endpoint to transfer participant to.
play_dialtoneboolOptionally play dial tone during the transfer. By default, the room audio is played during the transfer.

Types

The SIP service includes the following types.

GetSIPInboundTrunkResponse

FieldTypeDescription
trunkSIPInboundTrunkInfoInbound trunk.

GetSIPOutboundTrunkResponse

FieldTypeDescription
trunkSIPOutboundTrunkInfoOutbound trunk.

SIPDispatchRule

Valid values include:

NameTypeValueDescription
dispatch_rule_directSIPDispatchRuleDirect1Dispatches callers into an existing room. You can optionally require a pin before caller enters the room.
dispatch_rule_individualSIPDispatchRuleIndividual2Creates a new room for each caller.
dispatch_rule_calleeSIPDispatchRuleCallee3Creates a new room for each callee.

SIPDispatchRuleInfo

FieldTypeDescription
sip_dispatch_rule_idstringDispatch rule ID.
ruleSIPDispatchRule
trunk_idsarray<string>List of associated trunk IDs.
hide_phone_numberboolIf true, hides phone number.
inbound_numbersarray<string>If this list is included, the dispatch rule only accepts calls made to the numbers in the list.
namestringHuman-readable name for the dispatch rule.
metadatastringUser-defined metadata for the dispatch rule. Participants created by this rule inherit this metadata.
headersmap<string, string>Custom SIP X-* headers to included in the 200 OK response.
attributesmap<string, string>Key-value mapping of user-defined attributes. Participants created by this rule inherit these attributes.

SIPInboundTrunkInfo

FieldTypeDescription
sip_trunk_idstringTrunk ID
namestringHuman-readable name for the trunk.
numbersarray<string>Phone numbers associated with the trunk. The trunk only accepts calls made to the phone numbers in the list.
allowed_addressesarray<string>IP addresses or CIDR blocks that are allowed to use the trunk. If this list is populated, the trunk only accepts traffic from the IP addresses in the list.
allowed_numbersarray<string>Phone numbers that are allowed to dial in. If this list is populated, the trunk only accepts calls from the numbers in the list.
auth_usernamestringUsername used to authenticate inbound SIP invites.
auth_passwordstringPassword used to authenticate inbound SIP invites.
headersmap<string, string>Custom SIP X-* headers to included in the 200 OK response.
headers_to_attributesmap<string, string>Custom SIP X-* headers that map to SIP participant attributes.
ringing_timeoutgoogle.protobuf.DurationMaximum time for the caller to wait for track subscription (that is, for the call to be picked up).
max_call_durationgoogle.protobuf.DurationMaximum call duration.
krisp_enabledBooleanTrue if krisp is enabled for the call.

SIPOutboundTrunkInfo

FieldTypeDescription
sip_trunk_idstringTrunk ID.
namestringTrunk name.
metadatastringUser-defined metadata for trunk.
addressstringHostname or IP address the SIP request message (SIP INVITE) is sent to.
transportSIPTransport (enum)
  • SIP_TRANSPORT_AUTO: 0
  • SIP_TRANSPORT_UDP: 1
  • SIP_TRANSPORT_TCP: 2
  • SIP_TRANSPORT_TLS: 3
numbersarray<string>Phone numbers used to make calls. A random number in the list is selected whenever a call is made.
auth_usernamestringUsername used to authenticate with the SIP server.
auth_passwordstringPassword used to authenticate with the SIP server.
headersmap<string, string>Custom SIP X-* headers to included in the 200 OK response.
headers_to_attributesmap<string, string>Custom SIP X-* headers that map to SIP participant attributes.

SIPParticipantInfo

FieldTypeDescription
participant_idstringParticipant ID.
participant_identitystringParticipant name.
room_namestringName of the room.
sip_call_idstringSIP call ID.

SIPTransport

Enum. Valid values are the following:

NameValue
SIP_TRANSPORT_AUTO0
SIP_TRANSPORT_UDP1
SIP_TRANSPORT_TCP2
SIP_TRANSPORT_TLS3

SIPTrunkInfo

note

This type is deprecated. See SIPInboundTrunkInfo and SIPOutboundTrunkInfo.

FieldTypeDescription
sip_trunk_idstringTrunk ID.
kindTrunkKindType of trunk.
inbound_addressesarray<string>IP addresses or CIDR blocks that are allowed to use the trunk. If this list is populated, the trunk only accepts traffic from the IP addresses in the list.
outbound_addressstringIP address that the SIP INVITE is sent to.
outbound_numberstringPhone number used to make outbound calls.
transportSIPTransportTransport protocol used for inbound and outbound calls.
inbound_numbersarray<string>If this list is populated, the trunk only accepts calls to the numbers in this list.
inbound_usernamestringUsername used to authenticate inbound SIP invites.
inbound_passwordstringPassword used to authenticate inbound SIP invites.
outbound_usernamestringUsername used to authenticate outbound SIP invites.
outbound_passwordstringPassword used to authenticate outbound SIP invites.
namestringTrunk name.
metadatastringInitial metadata to assign to the trunk. This metadata is added to every SIP participant that uses the trunk.

TrunkKind

Enum. Valid values are the following:

NameValue
TRUNK_LEGACY0
TRUNK_INBOUND1
TRUNK_OUTBOUND2