Transferring calls | LiveKit Docs

A "cold transfer" refers to transferring a caller (SIP participant) to another number or SIP endpoint without a hand off. A cold transfer shuts down the room (that is, the session) of the original call.

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:

Note

To list trunks, execute twilio api trunking v1 trunks list.
To set the caller ID to the transferor, set transfer-caller-id to from-transferor.

twilio api trunking v1 trunks update --sid <twilio-trunk-sid> \
--transfer-mode enable-all \
--transfer-caller-id from-transferee

TransferSIPParticipant server API parameters

transfer_tostringRequired

The transfer_to value can either be a valid telephone number or a SIP URI. The following examples are valid values:

tel:+15105550100
sip:+15105550100@sip.telnyx.com
sip:+15105550100@my-livekit-demo.pstn.twilio.com

participant_identitystringRequired

Identity of the SIP participant that should be transferred.

room_namestringRequired

Source room name for the transfer.

play_dialtoneboolRequired

Play dial tone to the user being transferred when a transfer is initiated.

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');
}