> ## Documentation Index
> Fetch the complete documentation index at: https://www.voiceflow.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configure call transfers through the API

> Prefer the interface? Transfer a phone caller in Studio. Custom telephony clients must also implement the call-forward trace; a browser-only audio client has no provider…

Prefer the interface? [Transfer a phone caller in Studio](/docs/guides/studio/voice/transfer-calls). Custom telephony clients must also implement the [`call-forward` trace](/docs/api-reference/agent-runtime/voice/handoff); a browser-only audio client has no provider call to transfer.

## Before you begin

- A phone-call project and a test provider number or SIP connection.
- Its project ID, draft Environment alias and server-side API key with agent-update access.
- A phone/SIP destination you control and a configured condition for invoking the tool.

## Configure and verify the transfer

### 1. Read the current agent

Use [Get agent](/docs/api-reference/agent/get-agent) with `projectID` and `environmentAlias`. Retain the existing `callForwardTool` configuration so it can be restored. The v2 Agent API uses strings for tool addresses, rather than native editor Markup objects.

### 2. Configure the system tool

```bash title="Enable a phone transfer destination"
curl --fail-with-body --silent --show-error --request PATCH \
  'https://realtime-api.voiceflow.com/v2/stable/agent?projectID=YOUR_PROJECT_ID&environmentAlias=YOUR_DRAFT_ALIAS' \
  --header "Authorization: $VF_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"callForwardTool":{"enabled":true,"addressType":"phone","address":"+14165550123","description":"Transfer when the customer asks to speak to the support team.","messages":null,"toolSound":null}}'
```

Replace the example destination with your test number. For a SIP destination, use `addressType: "sip"` and the verified SIP address. The tool’s description tells the agent when it should be used; it is not a guarantee that any test utterance will invoke it.

### 3. Test the managed call

Compile the draft using [Compile environment](/docs/api-reference/environment/compile-environment), then make a real call through its assigned test connection. Request a person and confirm the provider connects the destination. For SIP, verify REFER acceptance on the PBX. Inspect the final call event and Transcript.

## Verify the result

Read the agent back and confirm the tool settings. Confirm an actual call reaches the intended destination. Do not interpret a saved configuration, a `call-forward` trace or a successful prototype as proof of a completed transfer.

## Recover a failed handoff

Restore the previous tool configuration if the destination or invocation condition is incorrect. For a rejected provider transfer, inspect its error and the call end reason before changing agent instructions. The documented contract does not supply native warm transfer or operator briefing.
