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 nobody decides within two minutes, 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.

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.

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, 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"
          }
        }
      }
    ]
  }'

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
          }
        }
      }
    ]
  }'

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

Conversations API

For AI Agents

Warm Transfer Acceptance

How it works

Configuration options

Context modes

Requirements

Setting up via API

Ask the destination to accept

Give each target its own handoff message

Combining with voicemail detection

​How it works

​Configuration options

​Context modes

​Requirements

​Setting up via API

​Ask the destination to accept

​Share the consult with the conversation record

​Give each target its own handoff message

​Combining with voicemail detection

​Related resources

How it works

Configuration options

Context modes

Requirements

Setting up via API

Ask the destination to accept

Share the consult with the conversation record

Give each target its own handoff message

Combining with voicemail detection

Related resources