TelephonySIP Trunks

Create SIP Trunk

Create a SIP trunk. For kind=byoc supply sip_address plus optional digest credentials and IP allowlist. For kind=twilio use ImportPhoneNumber with a twilio spec instead - trunk creation is handled automatically. Returns 402 when the workspace has reached the 20-trunk cap.

Authentication

AuthorizationBearer

Enter your API key with the Bearer prefix, e.g. ‘Bearer sk_…’.

Request

This endpoint expects an object.
namestringRequired

Human-readable name for the trunk.

kindenumRequired

Where the trunk came from. Informs the provisioning path and portability story.

  • livekit - Provisioned by LiveKit’s native phone-number API.
  • twilio - Backed by a Twilio Elastic SIP Trunk on the customer’s account.
  • byoc - Any SIP provider with a customer-managed trunk.
directionenumRequired

Whether the trunk handles inbound calls, outbound calls, or both. A both trunk has distinct LiveKit inbound and outbound trunk IDs.

sip_addressstringOptional

SIP endpoint hostname. Required for kind=byoc.

auth_usernamestringOptional
SIP digest auth username.
auth_passwordstringOptional

SIP digest auth password. Write-only.

allowed_addresseslist of stringsOptional

IP / CIDR allowlist for inbound connections. Empty means any source is accepted.

destination_countrystringOptional

ISO 3166-1 alpha-2 country for the outbound dial plan.

transportenumOptional

SIP transport protocol. auto lets LiveKit negotiate. Use tls for production where available - note that TLS is incompatible with SIP REFER (cold transfer). Trunks that need transfer_to_number should use udp or tcp.

media_encryptionenumOptional

SRTP media encryption policy.

  • disable - Unencrypted media only.
  • allow - Negotiate SRTP; fall back to unencrypted. Recommended default.
  • require - Reject calls that do not support SRTP.
credentialsobjectOptional

Provider-specific credential blob (for future extensibility).

Response

The created SIP trunk.
idstring

Prefixed wire identifier (trunk_<26 char Crockford base32>). ADR 0015 Cluster 3 hard-break: URL paths accept only this prefixed form; legacy UUID path parameters are rejected with 404 as of Cluster 3.

namestring

Human-readable name.

kindenum

Where the trunk came from. Informs the provisioning path and portability story.

  • livekit - Provisioned by LiveKit’s native phone-number API.
  • twilio - Backed by a Twilio Elastic SIP Trunk on the customer’s account.
  • byoc - Any SIP provider with a customer-managed trunk.
directionenum

Whether the trunk handles inbound calls, outbound calls, or both. A both trunk has distinct LiveKit inbound and outbound trunk IDs.

allowed_addresseslist of strings

IP address / CIDR allowlist for inbound SIP connections.

transportenum

SIP transport protocol. auto lets LiveKit negotiate. Use tls for production where available - note that TLS is incompatible with SIP REFER (cold transfer). Trunks that need transfer_to_number should use udp or tcp.

media_encryptionenum

SRTP media encryption policy.

  • disable - Unencrypted media only.
  • allow - Negotiate SRTP; fall back to unencrypted. Recommended default.
  • require - Reject calls that do not support SRTP.
created_atdatetime
updated_atdatetime
livekit_inbound_trunk_idstring

LiveKit’s inbound trunk ID (present when direction is inbound or both).

livekit_outbound_trunk_idstring

LiveKit’s outbound trunk ID (present when direction is outbound or both).

livekit_dispatch_rule_idstring
LiveKit dispatch rule ID that routes inbound calls into rooms.
sip_addressstring

SIP endpoint hostname (e.g. sip.telnyx.com). Required for kind=byoc.

auth_usernamestring
SIP digest auth username.
auth_password_setboolean
Whether a SIP digest auth password is configured. The value is never returned.
destination_countrystring

ISO 3166-1 alpha-2 country code for the outbound dial plan (e.g. US, DE). Required for international outbound on some carriers.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error