Skip to main content
POST
Handler for POST /sip/transfer endpoint
Initiates a SIP REFER transfer for a participant in a LiveKit room. The transfer moves an ongoing SIP call to a different phone number.

Authorization

Access is controlled via room metadata:
Room names are used exactly as provided. No prefixing or modification is applied.

Request

Requires:
  • room_name - The LiveKit room where the SIP participant is connected
  • participant_identity - The identity of the SIP participant to transfer
  • transfer_to - The destination phone number
Phone numbers support international format (+1234567890), national format (07123456789), or internal extensions (1234).

Response

Returns status of initiated once the transfer request is accepted. A successful response indicates the transfer has been initiated, not that it has completed.

Error responses

Only SIP participants can be transferred. Use GET /livekit/rooms/{room_name} to check if a participant has kind: "SIP" before attempting a transfer.

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 a SIP call transfer

Example

participant_identity
string
required

The identity of the SIP participant to transfer. This can be obtained by listing participants in the room via LiveKit API.

Example:

"sip_participant_456"

room_name
string
required

The LiveKit room name where the SIP participant is connected

Example:

"call-room-123"

transfer_to
string
required

The phone number to transfer the call to. Supports international format (+1234567890), national format (07123456789), or internal extensions (1234).

Example:

"+15551234567"

Response

Transfer initiated successfully

Response for a successful SIP transfer initiation

Note: A successful response indicates the transfer has been initiated, not that it has completed. The actual transfer may take several seconds.

Example

participant_identity
string
required

The identity of the participant being transferred

Example:

"sip_participant_456"

room_name
string
required

The room name where the transfer was initiated

Example:

"call-room-123"

status
string
required

Status of the transfer request ("initiated" or "completed")

Example:

"initiated"

transfer_to
string
required

The normalized phone number with tel: prefix

Example:

"tel:+15551234567"