Transfer outcome states

Every call transfer reports how it ended. Use these values to track how often transfers connect, drive fallback logic, and debug individual calls.

• Outcome states say whether the transfer connected, and if not, what got in the way.
• Transfer modes decide what happens next: warm transfers can recover, while a cold transfer ends the call.
• Failure reasons name the specific cause, such as a busy line, an IVR menu, or a wrong number.

Where the values appear

The outcome is saved on the transfer action of each call:

• Get a call and List calls return it in executed_actions, keyed by action name, as return_value.status and return_value.failed_reason.
• The post-call webhook sends the same executed_actions object.
• The action execution timeline records a failed_reason for every failed attempt, so a transfer that retried shows the cause of each try. Its status field is started, success, or failed rather than an outcome state.

{
    "executed_actions": {
        "action_transfer_call": {
            "name": "action_transfer_call",
            "action_type": "transfer_call_action_type",
            "return_value": {
                "status": "transfer-failed-connection-error",
                "failed_reason": "number_not_found"
            }
        }
    }
}

Outcome states

How each transfer mode reacts

Some outcome states depend on features that only warm transfers support, so a cold transfer never produces them.

Failure reasons

Reach for the failure reason when the outcome state on its own is not specific enough, for example to tell an unanswered ring apart from a wrong number. The reasons below are grouped by what caused the failure.

Human detection

These reasons are only set when Human Detection is enabled on a warm transfer.

Busy lines, hang-ups, and declines

Carrier and SIP rejections

The carrier returned a SIP error before the transfer leg connected. All of these report the outcome state transfer-failed-connection-error.

Availability and fallback

Timestamps

A transfer records up to two timestamps, both in ISO 8601 UTC. The gap between them is how long the caller waited between asking for a person and reaching one.

Both appear on the transfer action in the same places as the outcome state.

Legacy values

Some values changed as transfer reporting became more specific. If your reporting or automation groups transfers by outcome state or failure reason, add the current values so these calls are not counted as generic failures.

FAQ