Skip to main content
POST
/
sip
/
transfer
Handler for POST /sip/transfer endpoint
curl --request POST \
  --url https://api.sayna.ai/sip/transfer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "participant_identity": "sip_participant_456",
  "room_name": "call-room-123",
  "transfer_to": "+15551234567"
}
'
{
  "participant_identity": "sip_participant_456",
  "room_name": "call-room-123",
  "status": "initiated",
  "transfer_to": "tel:+15551234567"
}
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:
ModeBehavior
Authenticated (auth.id present)Requires room.metadata.auth_id == auth.id.
Unauthenticated (auth.id absent)Access is allowed (backward-compatible mode).
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

StatusCondition
400 Bad RequestInvalid phone number format or empty required fields.
404 Not FoundRoom not found, access denied, or participant not found/not a SIP participant.
500 Internal Server ErrorLiveKit not configured or transfer operation failed.
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

JWT token obtained from the authentication service. Required when AUTH_REQUIRED is enabled.

Body

application/json

Request body for initiating a SIP call transfer

Example

{
  "room_name": "call-room-123",
  "participant_identity": "sip_participant_456",
  "transfer_to": "+15551234567"
}
​
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

{
  "status": "initiated",
  "room_name": "call-room-123",
  "participant_identity": "sip_participant_456",
  "transfer_to": "tel:+15551234567"
}
​
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"