A cold transfer refers to forwarding a caller to another phone number or SIP endpoint. Performing a cold transfer closes the caller’s LiveKit session.
For transfers that include an AI agent to provide context, see the Agent-assisted transfer guide.
How it works
To transfer a caller out of a LiveKit room to another phone number, use the following steps:
- Call the
TransferSIPParticipant
API. - LiveKit sends a SIP REFER through your trunk, instructing the provider to connect the caller to the new number or SIP endpoint.
- The caller leaves the LiveKit room, ending the session.
Transferring a SIP participant using SIP REFER
REFER is a SIP method that allows you to move an active session to another endpoint (that is, transfer a call). For LiveKit telephony apps, you can use the TransferSIPParticipant
server API to transfer a caller to another phone number or SIP endpoint.
In order to successfully transfer calls, you must configure your provider trunks to allow call transfers.
Enable call transfers for your Twilio SIP trunk
Enable call transfer and PSTN transfers for your Twilio SIP trunk. To learn more, see Twilio's Call Transfer via SIP REFER documentation.
When you transfer a call, you have the option to set the caller ID to display the phone number of the transferee (the caller) or the transferor (the phone number associated with your LiveKit trunk).
The following command enables call transfers and sets the caller ID to display the number of the transferee:
- To list trunks, execute
twilio api trunking v1 trunks list
. - To set the caller ID to the transferor, set
transfer-caller-id
tofrom-transferor
.
twilio api trunking v1 trunks update --sid <twilio-trunk-sid> \--transfer-mode enable-all \--transfer-caller-id from-transferee
- Sign in to the Twilio console.
- Navigate to Elastic SIP Trunking » Manage » Trunks, and select a trunk.
- In the Features » Call Transfer (SIP REFER) section, select Enabled.
- In the Caller ID for Transfer Target field, select an option.
- Select Enable PSTN Transfer.
- Save your changes.
Usage
Set up the following environment variables:
export LIVEKIT_URL=<your LiveKit server URL>export LIVEKIT_API_KEY=<your API Key>export LIVEKIT_API_SECRET=<your API Secret>
This example uses the LiveKit URL, API key, and secret set as environment variables.
import { SipClient } from 'livekit-server-sdk';// ...async function transferParticipant(participant) {console.log("transfer participant initiated");const sipTransferOptions = {playDialtone: false};const sipClient = new SipClient(process.env.LIVEKIT_URL,process.env.LIVEKIT_API_KEY,process.env.LIVEKIT_API_SECRET);const transferTo = "tel:+15105550100";await sipClient.transferSipParticipant('open-room', participant.identity, transferTo, sipTransferOptions);console.log('transfer participant');}
import asyncioimport loggingimport osfrom livekit import apifrom livekit.protocol.sip import TransferSIPParticipantRequestlogger = logging.getLogger("transfer-logger")logger.setLevel(logging.INFO)async def transfer_call(participant_identity: str, room_name: str) -> None:async with api.LiveKitAPI() as livekit_api:transfer_to = 'tel:+14155550100'# Create transfer requesttransfer_request = TransferSIPParticipantRequest(participant_identity=participant_identity,room_name=room_name,transfer_to=transfer_to,play_dialtone=False)logger.debug(f"Transfer request: {transfer_request}")# Transfer callerawait livekit_api.sip.transfer_sip_participant(transfer_request)logger.info(f"Successfully transferred participant {participant_identity} to {transfer_to}")
For a full example using a voice agent, DTMF, and SIP REFER, see the phone assistant example.
require 'livekit'room_name = 'open-room'participant_identity = 'participant_identity'def transferParticipant(room_name, participant_identity)sip_service = LiveKit::SIPServiceClient.new(ENV['LIVEKIT_URL'],api_key: ENV['LIVEKIT_API_KEY'],api_secret: ENV['LIVEKIT_API_SECRET'])transfer_to = 'tel:+14155550100'sip_service.transfer_sip_participant(room_name,participant_identity,transfer_to,play_dialtone: false)end
import ("context""fmt""os"lksdk "github.com/livekit/server-sdk-go/v2""github.com/livekit/protocol/livekit")func transferParticipant(ctx context.Context, participantIdentity string) {roomName := "open-room"transferTo := "tel:+14155550100'// Create a transfer requesttransferRequest := &livekit.TransferSIPParticipantRequest{RoomName: roomName,ParticipantIdentity: participantIdentity,TransferTo: transferTo,PlayDialtone: false,}sipClient := lksdk.NewSIPClient(os.Getenv("LIVEKIT_URL"),os.Getenv("LIVEKIT_API_KEY"),os.Getenv("LIVEKIT_API_SECRET"))// Execute transfer request_, err := sipClient.TransferSIPParticipant(ctx, transferRequest)if err != nil {fmt.Println(err)}}
lk sip participant transfer --room <CURRENT_ROOM> \--identity <PARTICIPANT_ID> \--to "<SIP_ENDPOINT>
Where <SIP_ENDPOINT>
is a valid SIP endpoint or telephone number. The following examples are valid formats:
tel:+15105550100
sip:+15105550100@sip.telnyx.com
sip:+15105550100@my-livekit-demo.pstn.twilio.com