Skip to main content
IntroductionBuild AgentsAgent FrontendsTelephonyWebRTC TransportManage & DeployReferences
XYouTubeSlack

WarmTransferTask

Execute an agent-assisted warm transfer with SIP dialing, hold music, and context handoff.

On this page

Overview Usage Parameters
Available inPython
|
Node.js

Overview

Use WarmTransferTask to execute an agent-assisted warm transfer. The task automatically manages the complexities of the transfer workflow, including dialing the human agent, providing context, and merging the calls.

WarmTransferTask handles the following:

  • Creating a separate room for the human agent.
  • Dialing the human agent using SIP.
  • Playing hold music to the caller while connecting.
  • Providing the human agent with conversation history and context.
  • Disabling I/O for the caller during the transfer process.
  • Providing tools for the human agent to:
    • connect_to_caller: Connect the human agent to the original caller.
    • decline_transfer: Decline the transfer with a reason.
    • voicemail_detected: Handle voicemail detection.

The task returns a WarmTransferResult data class with one field: human_agent_identity (humanAgentIdentity in Node.js).

Agent-assisted warm transfer

A comprehensive guide to transferring calls using an AI agent to provide context.

Usage

For a basic example, see the following code snippet:

import os


from livekit.agents.beta.workflows import WarmTransferTask
from livekit.protocol.sip import SIPOutboundConfig


result = await WarmTransferTask(
    sip_call_to=<human-agent-phone-number>,         # Human agent's phone number
    sip_connection=SIPOutboundConfig(               # Inline trunk configuration
        hostname=os.getenv("SIP_TRUNK_HOSTNAME"),
        auth_username=os.getenv("SIP_AUTH_USERNAME"),
        auth_password=os.getenv("SIP_AUTH_PASSWORD"),
    ),
    chat_ctx=self.chat_ctx,                         # Conversation history
)
import { workflows } from '@livekit/agents';


const result = await new workflows.WarmTransferTask({
  sipCallTo: '<human-agent-phone-number>', // Human agent's phone number
  sipTrunkId: process.env.LIVEKIT_SIP_OUTBOUND_TRUNK, // Stored outbound trunk ID
  chatCtx: this.chatCtx, // Conversation history
  instructions: { extra: '<summary-instructions>' },
}).run();
Stored outbound trunk

You can also use a stored outbound trunk by passing sip_trunk_id instead of sip_connection. For details, see Outbound trunk. You can set the trunk ID with the LIVEKIT_SIP_OUTBOUND_TRUNK environment variable.

Node.js namespace

In Node.js (v1.5+), WarmTransferTask is part of the stable workflows namespace — import it as workflows.WarmTransferTask and use camelCase options. In Python, it remains under beta.workflows.

Parameters

For a full list of parameters, see the WarmTransferTask reference.

You can customize the behavior of WarmTransferTask by passing additional parameters:

sip_call_to
Required
string

The phone number or SIP URI to dial for the warm transfer.

sip_trunk_idstringEnv: LIVEKIT_SIP_OUTBOUND_TRUNK

The outbound SIP trunk ID to use for dialing. Either sip_trunk_id or sip_connection is required. You can also set this with the LIVEKIT_SIP_OUTBOUND_TRUNK environment variable.

sip_connectionapi.SIPOutboundConfig

Inline trunk configuration. Pass trunk settings directly instead of using a stored trunk. You can specify a custom hostname, transport protocol, or authentication credentials.

Either sip_connection or sip_trunk_id is required.

sip_numberstringEnv: LIVEKIT_SIP_NUMBER

The SIP "From" number to use as the caller ID. If empty, the trunk number is used. You can also set this with the LIVEKIT_SIP_NUMBER environment variable.

sip_headersdict[str, str]

Custom SIP headers included as-is in the outbound INVITE request. Use this to pass metadata that identifies the call to the remote SIP endpoint.

dtmfstr | None

DTMF tones to send after the human agent answers the call. Use this to dial an extension or navigate an interactive voice response (IVR) menu. Insert w characters to pause ~0.5 seconds each before or between digits. For example, "wwww1234#" waits ~2 seconds then dials extension 1234.

ringing_timeoutfloat | None

Seconds to wait for the human agent to answer before giving up. When the timeout elapses, the task completes with a ToolError and the caller conversation resumes.

hold_audioAudioSource | AudioConfig | list | NoneDefault: BuiltinAudioClip.HOLD_MUSIC

Audio to play while the caller is on hold. By default, plays BuiltinAudioClip.HOLD_MUSIC.

Default hold music

Default hold music light waveform
extra_instructionsstring

Additional instructions for the transfer agent. These instructions are passed to the transfer agent along with the conversation history and the default instructions.

callerHangupInstructionstring
Only Available inNode.js

Instructions used to generate the message the human agent hears if the caller hangs up mid-transfer. Their call ends after the message plays. By default, the message conveys that the caller has left and the call is ending.

toolslist

Additional tools that can be used in the execution of the transfer task. These tools can be used in place of, or in addition to, the default tools.