SIP transfer
Initiates a SIP REFER transfer for a participant in a LiveKit room. The transfer moves an ongoing SIP call to a different phone number.
Arguments
state- Shared application state containing LiveKit handlersauth- Authentication context for room metadata authorizationrequest- Transfer request with room name, participant identity, and destination
Returns
Response- JSON response with transfer status or error
Errors
- 400 Bad Request - Invalid phone number format or empty fields
- 404 Not Found - Room not found, not accessible, or participant not found
- 500 Internal Server Error - LiveKit not configured or transfer operation failed
Flow
- Validate the phone number format
- Check LiveKit handlers are configured
- Check room access via metadata auth_id
- Verify the participant exists and is a SIP participant
- Execute the SIP transfer
- Return success or appropriate error
Authorization
Access is controlled via room metadata:| Mode | Behavior |
|---|---|
Authenticated (auth.id present) | Requires room.metadata.auth_id == auth.id. |
Unauthenticated (auth.id absent) | Access is allowed (backward-compatible mode). |
Request
Requires:room_name- The LiveKit room where the SIP participant is connectedparticipant_identity- The identity of the SIP participant to transfertransfer_to- The destination phone number
+1234567890), national format (07123456789), or internal extensions (1234).
Response
Returnsstatus of initiated once the transfer request is accepted. A successful response indicates the transfer has been initiated, not that it has completed.
Error responses
| Status | Condition |
|---|---|
400 Bad Request | Invalid phone number format or empty required fields. |
404 Not Found | Room not found, access denied, or participant not found/not a SIP participant. |
500 Internal Server Error | LiveKit not configured or transfer operation failed. |
Authorizations
Authentication token for protected endpoints. Can be provided as Authorization: Bearer <token> or ?api_key=<token>. Required when AUTH_REQUIRED is enabled.
Body
Request body for initiating a SIP call transfer
Example
{
"room_name": "call-room-123",
"participant_identity": "sip_participant_456",
"transfer_to": "+15551234567"
}The identity of the SIP participant to transfer. This can be obtained by listing participants in the room via LiveKit API.
"sip_participant_456"
The LiveKit room name where the SIP participant is connected
"call-room-123"
The phone number to transfer the call to. Supports international format (+1234567890), national format (07123456789), or internal extensions (1234).
"+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
{
"status": "initiated",
"room_name": "call-room-123",
"participant_identity": "sip_participant_456",
"transfer_to": "tel:+15551234567"
}The identity of the participant being transferred
"sip_participant_456"
The room name where the transfer was initiated
"call-room-123"
Status of the transfer request ("initiated" or "completed")
"initiated"
The normalized phone number with tel: prefix
"tel:+15551234567"