Skip to main content
POST
Handler for POST /sip/call endpoint
Initiate an outbound SIP call through LiveKit. The call is connected to the specified room as a SIP participant, enabling real-time voice interactions with external phone numbers.
Requires SIP configuration with an outbound_address and a valid SIP trunk. The room is created automatically if it doesn’t exist, with metadata.auth_id set for tenant isolation.

Request fields

SIP configuration overrides

The optional sip object allows you to override global SIP configuration on a per-request basis. This is useful when you need to use different SIP providers or credentials for specific calls.
Existing requests without the sip object continue to work unchanged. The global server configuration is used when per-request overrides are not provided.

Configuration priority

When the sip object is provided, its fields take priority over global server configuration: Request body sip config > Global server config
If neither the request body nor global config provides an outbound_address, the call will fail with an OUTBOUND_ADDRESS_NOT_CONFIGURED error.

Example requests

Authorization

Access is controlled via room metadata:
  • When auth.id is present and the room exists: requires room.metadata.auth_id == auth.id
  • When auth.id is present and room doesn’t exist: room is created with metadata.auth_id set
  • When auth.id is absent: access is allowed (backward-compatible mode)

Error responses

Phone numbers support international format (+1234567890), national format (07123456789), or internal extensions (1234).

Authorizations

Authorization
string
header
required

Authentication token for protected endpoints. Can be provided as Authorization: Bearer <token> or ?api_key=<token>. Required when AUTH_REQUIRED is enabled.

Body

application/json

Request body for initiating an outbound SIP call

Example

SIP Configuration Priority

The sip object is optional. When provided, its fields take priority over global server configuration values. This allows per-request customization of SIP settings.

Priority order: Request body sip config > Global server config

  • outbound_address: Overrides sip.outbound_address from config
  • auth_username: Overrides sip.outbound_auth_username from config
  • auth_password: Overrides sip.outbound_auth_password from config

If neither the request body nor global config provides an outbound_address, the call will fail with OUTBOUND_ADDRESS_NOT_CONFIGURED error.

from_phone_number
string
required

Phone number the call will originate from. Must be configured in your SIP provider. Supports international format (+1234567890).

Example:

"+15105550123"

participant_identity
string
required

Identity for the SIP participant in the room

Example:

"caller-456"

participant_name
string
required

Display name for the SIP participant in the room

Example:

"John Doe"

room_name
string
required

The LiveKit room name to connect the call to

Example:

"call-room-123"

to_phone_number
string
required

Phone number to dial. Supports international format (+1234567890), national format (07123456789), or extensions (1234).

Example:

"+15551234567"

sip
null | object

Optional per-request SIP configuration overrides. When provided, these values take priority over the global server configuration. This allows using different SIP providers or credentials for specific calls.

Response

Call initiated successfully

Response for a successful SIP call initiation

Example

participant_id
string
required

The unique participant ID assigned by LiveKit

Example:

"PA_abc123"

participant_identity
string
required

The identity of the SIP participant in the room

Example:

"caller-456"

room_name
string
required

The room name where the call was connected

Example:

"call-room-123"

sip_call_id
string
required

The unique SIP call ID for tracking

Example:

"SC_xyz789"

status
string
required

Status of the call request ("initiated")

Example:

"initiated"