Warm Transfer Acceptance

A warm transfer normally plays a recorded handoff message to the destination and then bridges the calls, whether or not the destination is ready to take them. Warm transfer acceptance adds a live consult step: once the destination answers, the assistant speaks with them privately, delivers the handoff context, and asks whether they accept the call. Only an explicit acceptance bridges the caller. While the consult happens, the caller stays with the assistant and keeps hearing ringback — they never hear the exchange.

How it works

The assistant calls the transfer tool and Telnyx dials the selected target.
The destination answers. Instead of playing recorded audio, the assistant joins the destination on a private leg.
The assistant delivers the warm transfer message and asks whether they take the call.
The assistant finalizes the transfer with the built-in complete_transfer tool:
- Accept — the caller and the destination are bridged and the assistant leaves the call.
- Decline — the destination leg is hung up and the assistant returns to the caller with the reason the destination gave.
If the destination hangs up, or does not accept within timeout_secs of the consult starting (60 seconds by default), the destination leg is dropped and the assistant returns to the caller.

The complete_transfer tool is added to the assistant automatically when acceptance is enabled — you do not configure it. If your assistant already has a tool named complete_transfer, acceptance is disabled on that assistant to avoid a name collision, so pick a different name for your own tool.

Configuration options

Acceptance is configured inside the transfer tool, under warm_transfer_acceptance:

Field	Type	Default	Description
`enabled`	boolean	`false`	Whether the destination must accept before the calls are bridged.
`end_user_target_context_mode`	`private` \| `shared`	`private`	Whether the consult with the destination is kept out of the conversation.
`require_acceptance`	boolean	`false`	Fail closed when the consult cannot be set up: treat it as a decline instead of degrading to a warm transfer playback and bridge.
`timeout_secs`	integer (10–600)	`60`	How long, in seconds, the destination has to accept, counted from when the private consult starts (right after it answers, or after `warm_message_delay_ms`). On expiry the destination is hung up and the assistant returns to the caller.

Context modes

The consult is a real conversation between your assistant and the destination, so you choose whether it becomes part of the conversation record:

Mode	Behavior
`private`	The exchange never reaches the conversation history, AI Conversations, webhooks or insights. The caller-facing turn only sees the transfer tool result, rewritten with the outcome — including the reason on a decline. Use this when the handoff may contain notes the caller should not see.
`shared`	The exchange stays in the conversation like any other messages, and is available in history, webhooks and insights.

Strict fail-closed: `require_acceptance`

By default (require_acceptance unset or false), a consult that cannot be set up degrades gracefully and the transfer still happens. Set require_acceptance to true when no bridge may happen without an explicit acceptance: the consult failing to start is then treated as a decline — the destination is disconnected without ever being asked, the assistant returns to the caller, and no bridge happens. This applies everywhere acceptance cannot run, including the situations listed under Requirements — gather_using_ai, Conversation Relay and web calls, conferences, and conversations with additional invited user participants: with the default, those paths fall back to a regular warm transfer and bridge anyway; with require_acceptance: true they fail closed instead, like any other consult that could not be set up. If your transfers can originate in those contexts, the flag is what makes “no acceptance, no bridge” hold on all of them. On every consult that does run, the destination must still explicitly accept before the caller is bridged, and an accept sent before the destination has answered the assistant’s question is refused — the phase stays live and the destination still gets to decide. This always-on guard is not configurable: it is active on every acceptance-enabled transfer, whatever require_acceptance is set to.

Choosing the acceptance timeout: `timeout_secs`

The timeout starts when the private consult begins — right after the destination answers, or once warm_message_delay_ms has elapsed — not when it is dialed. While it runs, the caller keeps hearing ringback. If no acceptance arrives before it expires, the destination is hung up, the transfer fails as a timeout, and the assistant returns to the caller. The 60-second default suits destinations where a person answers directly. Raise it when the destination answers before a human is on the line — for example a call-center queue or ACD (such as Genesys) or an IVR that picks up immediately with hold audio — so the consult does not expire while the call waits for an agent. Keep it as short as practical: the caller waits on ringback for the whole timeout.

Requirements

A warm message must always be available. Set warm_transfer_instructions on the transfer tool, or a message on every target. Saving an assistant with acceptance enabled and neither of these returns a validation error. When both are present, the target’s message wins.
Only for ai_assistant_start conversations. Acceptance does not apply to gather_using_ai, Conversation Relay, or web calls.
Single-caller conversations only. If the conversation is in a conference or has more than one invited user participant, the transfer falls back to a regular warm transfer with recorded playback.

If the consult cannot be set up for any reason and require_acceptance is unset or false, the transfer degrades gracefully: the warm transfer message is played to the destination as audio and the calls are bridged, exactly as a warm transfer without acceptance.

Setting up via API

Configure warm_transfer_acceptance within the transfer tool when creating or updating an assistant.

Ask the destination to accept

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "name": "Support Agent",
    "instructions": "You are a support agent. Transfer calls to the support team when the caller asks for a human.",
    "model": "moonshotai/Kimi-K2.5",
    "tools": [
      {
        "type": "transfer",
        "transfer": {
          "targets": [
            {
              "name": "Support Team",
              "to": "+15551234567"
            }
          ],
          "from": "+15553456789",
          "warm_transfer_instructions": "Briefly summarize why the caller is being transferred and what they already tried. Then ask whether they can take the call.",
          "warm_transfer_acceptance": {
            "enabled": true
          }
        }
      }
    ]
  }'

Set end_user_target_context_mode to shared when you want the exchange with the destination stored alongside the rest of the conversation:

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "name": "Support Agent",
    "instructions": "You are a support agent. Transfer calls to the support team when the caller asks for a human.",
    "model": "moonshotai/Kimi-K2.5",
    "tools": [
      {
        "type": "transfer",
        "transfer": {
          "targets": [
            {
              "name": "Support Team",
              "to": "+15551234567"
            }
          ],
          "from": "+15553456789",
          "warm_transfer_instructions": "Briefly summarize why the caller is being transferred and what they already tried. Then ask whether they can take the call.",
          "warm_transfer_acceptance": {
            "enabled": true,
            "end_user_target_context_mode": "shared"
          }
        }
      }
    ]
  }'

Never bridge without an acceptance

Set require_acceptance to true for strict fail-closed behavior: a consult that cannot be set up is treated as a decline instead of degrading to a warm transfer playback and bridge.

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "name": "Support Agent",
    "instructions": "You are a support agent. Transfer calls to the support team when the caller asks for a human.",
    "model": "moonshotai/Kimi-K2.5",
    "tools": [
      {
        "type": "transfer",
        "transfer": {
          "targets": [
            {
              "name": "Support Team",
              "to": "+15551234567"
            }
          ],
          "from": "+15553456789",
          "warm_transfer_instructions": "Briefly summarize why the caller is being transferred and what they already tried. Then ask whether they can take the call.",
          "warm_transfer_acceptance": {
            "enabled": true,
            "require_acceptance": true
          }
        }
      }
    ]
  }'

Allow more time for queue or IVR destinations

Raise timeout_secs when the destination is a queue or IVR that answers before an agent picks up:

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "name": "Support Agent",
    "instructions": "You are a support agent. Transfer calls to the support team when the caller asks for a human.",
    "model": "moonshotai/Kimi-K2.5",
    "tools": [
      {
        "type": "transfer",
        "transfer": {
          "targets": [
            {
              "name": "Support Queue",
              "to": "+15551234567"
            }
          ],
          "from": "+15553456789",
          "warm_transfer_instructions": "Briefly summarize why the caller is being transferred and what they already tried. Then ask whether they can take the call.",
          "warm_transfer_acceptance": {
            "enabled": true,
            "timeout_secs": 180
          }
        }
      }
    ]
  }'

Give each target its own handoff message

A message on a target replaces the message the assistant would compose from warm_transfer_instructions, and satisfies the warm-message requirement on its own:

curl -L 'https://api.telnyx.com/v2/ai/assistants' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  --data-raw '{
    "name": "Support Agent",
    "instructions": "You are a support agent. Route callers to the right team.",
    "model": "moonshotai/Kimi-K2.5",
    "tools": [
      {
        "type": "transfer",
        "transfer": {
          "targets": [
            {
              "name": "Billing",
              "to": "+15551234567",
              "message": "I have a caller with a billing question. Can you take it?"
            },
            {
              "name": "Technical Support",
              "to": "+15557654321",
              "message": "I have a caller with a device issue that I could not resolve. Can you take it?"
            }
          ],
          "from": "+15553456789",
          "warm_transfer_acceptance": {
            "enabled": true
          }
        }
      }
    ]
  }'

Beep when the caller joins

The handoff message plays before the bridge, so on its own nothing tells the destination the exact moment the caller is connected. Set bridge_beep.enabled to true to play a short beep once the calls are bridged. It works with or without warm_transfer_acceptance. By default only the destination hears the beep ("target_legs": "self"). Set "target_legs": "both" to play it to the caller too.

"transfer": {
  "targets": [
    {
      "name": "Support Team",
      "to": "+15551234567"
    }
  ],
  "from": "+15553456789",
  "warm_transfer_instructions": "Briefly summarize why the caller is being transferred.",
  "bridge_beep": {
    "enabled": true,
    "target_legs": "self"
  }
}

Combining with voicemail detection

Acceptance works alongside voicemail detection on transfer. When AMD is enabled on the transfer, the consult starts once the destination is identified as a human. If voicemail is detected, the configured voicemail action runs instead — both stop_transfer and leave_message_and_stop_transfer end the transfer, so no consult takes place and the assistant returns to the caller.

Voice AI Assistant API Reference - Complete transfer tool API documentation, including the warm_transfer_acceptance parameters.
Voicemail Detection on Transfer - Detect voicemail on the transfer destination and respond automatically.
Agent Handoff - Hand a conversation from one assistant to another instead of to a human.
Attach an AI Assistant to a Call - Start an assistant on a live call with ai_assistant_start.

Guides

Missions

AI Insights

Assistants API

Missions API

AI Tests API

Conversations API

For AI Agents

Warm Transfer Acceptance

How it works

Configuration options

Context modes

Strict fail-closed: `require_acceptance`

Choosing the acceptance timeout: `timeout_secs`

Requirements

Setting up via API

Ask the destination to accept

Never bridge without an acceptance

Allow more time for queue or IVR destinations

Give each target its own handoff message

Beep when the caller joins

Combining with voicemail detection

​How it works

​Configuration options

​Context modes

​Strict fail-closed: require_acceptance

​Choosing the acceptance timeout: timeout_secs

​Requirements

​Setting up via API

​Ask the destination to accept

​Share the consult with the conversation record

​Never bridge without an acceptance

​Allow more time for queue or IVR destinations

​Give each target its own handoff message

​Beep when the caller joins

​Combining with voicemail detection

​Related resources

How it works

Configuration options

Context modes

Strict fail-closed: `require_acceptance`

Choosing the acceptance timeout: `timeout_secs`

Requirements

Setting up via API

Ask the destination to accept

Share the consult with the conversation record

Never bridge without an acceptance

Allow more time for queue or IVR destinations

Give each target its own handoff message

Beep when the caller joins

Combining with voicemail detection

Related resources