Assistant-Based Warm Transfer: Deep Dive

Overview

Call Forwarding & Transfer Modes briefly introduces assistant-based warm transfer — the warm-transfer-experimental mode's dedicated transfer assistant that talks to the operator directly and decides the outcome itself. This page is the deep dive on that mode: its full flow, the complete transferAssistant configuration surface, the two built-in tools in depth, and system prompt guidance.

1. The customer asks to be transferred (or the assistant decides a transfer is needed).
2. The customer is placed on hold.
3. A dedicated transfer assistant calls the operator.
4. The transfer assistant follows your configured system prompt and has access to the prior conversation's context, so it can brief the operator without the customer repeating themselves.
5. The transfer assistant calls either transferSuccessful or transferCancel to complete or abort the handoff.

The transfer is cancelled automatically — regardless of what the transfer assistant decides — when any of the following occur:

• maxDurationSeconds is reached.
• The operator doesn't answer.
• Voicemail is detected.
• A custom condition defined in your system prompt is met.

The transferAssistant object is configured inside the destination's transferPlan, with mode set to warm-transfer-experimental:

{
  "type": "transferCall",
  "function": {
    "name": "salesTransferAssistant"
  },
  "destinations": [
    {
      "type": "number",
      "number": "+14155551234",
      "transferPlan": {
        "mode": "warm-transfer-experimental",
        "transferAssistant": {
          "firstMessage": "Hello, I have a customer on the line. Are you available to take this call?",
          "firstMessageMode": "assistant-speaks-first",
          "maxDurationSeconds": 120,
          "silenceTimeoutSeconds": 30,
          "model": {
            "provider": "openai",
            "model": "gpt-4o",
            "messages": [
              {
                "role": "system",
                "content": "You are a transfer assistant. Use transferSuccessful when the operator agrees to accept the call. Use transferCancel when the transfer cannot be completed."
              }
            ]
          }
        }
      }
    }
  ]
}

Every transfer assistant has two built-in tools that are always present and cannot be removed:

• transferSuccessful — merges the customer and operator calls, removes the transfer assistant, and connects the two parties directly. Called when the operator agrees to accept the call.
• transferCancel — disconnects from the operator and returns the customer to the original assistant, optionally playing a fallback message. Called when the operator declines, voicemail is detected, or the transfer otherwise can't complete.

You can attach custom messages to either tool using three message types: request-start (spoken when the tool call begins), request-complete (spoken or played once it finishes), and request-failed (spoken if it errors). Example:

"tools": [
  {
    "type": "transferSuccessful",
    "function": {
      "name": "transferSuccessful",
      "description": "Confirm the transfer when operator accepts"
    },
    "messages": [
      {
        "type": "request-start",
        "content": "Great! I'll connect you to the customer now."
      },
      {
        "type": "request-complete",
        "content": "https://assets.sulus.ai/chime.mp3"
      }
    ]
  },
  {
    "type": "transferCancel",
    "function": {
      "name": "transferCancel",
      "description": "Cancel the transfer if operator declines or is unavailable"
    },
    "messages": [
      {
        "type": "request-complete",
        "content": "I'll let the customer know."
      }
    ]
  }
]

Because request-complete accepts either a spoken text string or a URL, you can point it at an audio file to play custom hold music while the transfer assistant is working the operator side of the transfer, instead of using the wording above for a spoken confirmation. If you don't specify one, a default ringtone plays while the customer is on hold.

Your transfer assistant's system prompt should explicitly handle:

• Voicemail detection — recognize an automated greeting and call transferCancel instead of talking to a machine.
• Human verification — confirm a real person answered before proceeding.
• Brief context for the operator — summarize who's calling and why, using the prior conversation's context.
• Rejection handling — define what to do if the operator declines the call.
• Staying within the time budget — wrap up the handoff decision before maxDurationSeconds is reached.

Example prompt:

You are a transfer assistant connecting a customer to an operator.

1. If you reach voicemail or an automated system, call transferCancel immediately.
2. Once a human answers, briefly explain: a customer is on the line, and why they need this operator.
3. If the operator agrees to take the call, call transferSuccessful.
4. If the operator declines or is unavailable, call transferCancel with a brief fallback message for the customer.
5. Keep this conversation under 90 seconds — don't let it run past the time budget.

• Requires the warm-transfer-experimental mode — it isn't available on the other warm transfer modes.
• Only works with certain phone number provisioning types — specifically platform-provided numbers and SIP trunks, not every external carrier import path.
• Bounded by maxDurationSeconds; the transfer is cancelled once that limit is reached regardless of the assistant's own decision.
• The two built-in tools, transferSuccessful and transferCancel, are predefined and cannot be removed.
• Recommended maxDurationSeconds range is 60–120 seconds — long enough for a real handoff conversation, short enough that the customer isn't left on hold too long.