Inbuilt tool - call_transfer

Back to Inbuilt tools The call_transfer tool transfers an active voice call to a SIP endpoint or a PSTN number from within an agent. Unlike ESCALATE, which routes a conversation through the platform’s human escalation workflow, call_transfer performs a direct telephony transfer. Use it when your agent needs to hand the active call to another SIP or PSTN destination without creating a human escalation task.

When to use

Use call_transfer when you want to:

Transfer the active call to a SIP endpoint or to a PSTN number.
Route calls programmatically based on business logic.
Integrate with external contact-center or telephony systems.

For structured human-agent escalation with routing rules, context propagation, and post-completion actions, use ESCALATE instead.

Declare the tool

call_transfer is an inbuilt tool, so it needs no HTTP endpoint or Tool Library entry. Declare it in the TOOLS: section so that your flow or reasoning agent can use it.

TOOLS:
  call_transfer(
      callTransferType: string,
      message: string
  ) -> object

An agent that routes through ESCALATE with voice.call_transfer_type: sip or pstn invokes call_transfer itself, so you do not declare the tool for that path. To call call_transfer from a flow or let the model call it, declare it as shown above. A CALL: call_transfer step in a flow without a TOOLS: declaration fails validation with an undefined-tool error.

Parameters

Parameter	Required	Description
`callTransferType`	Yes	Transfer type. Supported values: `sip`, `pstn`.
`message`	No	Message played to the caller before the transfer begins.
`language`	No	TTS language code for `message` (for example, `en-US`, `es-ES`).
`headers`	No	Custom SIP headers to forward on a SIP transfer. Only headers permitted by your transfer header policy are sent.

Where the destination comes from

For security, the destination is never taken from the model or from values passed in the call. The platform resolves it, so a prompt-injected conversation cannot redirect a live call. PSTN transfers dial the number configured in Project Settings > Agent Transfer > Voice Gateway. The number must be in E.164 format. If it is missing or invalid, the transfer fails and nothing is dialed. SIP transfers use the first destination available from this list:

The destination returned by a RESOLVE_SIP_DESTINATION step earlier in the flow.
The sip_transfer_id of the matching ESCALATE routing entry (when the transfer is triggered by escalation).
The sipTransferId default declared on the tool with default_source: config.
The SIP target configured in Project Settings > Agent Transfer > Voice Gateway.

If you declare approved_authorities on the tool (dynamic SIP routing), the transfer requires a routing decision for the call. When none exists, or the resolved destination is not on the approved list, the transfer fails closed. It does not fall back to the project default.

The transfer method (refer, invite, or bye) is also set in Project Settings, not in the call.

How it works

The platform resolves the destination for the current call, as described above.
For dynamic routing, the SIP URI template is filled with the routed values, and the result is validated against the approved authorities.
If message is set, it is played to the caller before the transfer starts.
The runtime dispatches the transfer and waits for the real SIP outcome. The tool reports success only when the call actually connected.
If the transfer fails, the caller stays with your agent and the flow follows the ON_FAILURE path.

On voice channels that cannot report a transfer outcome, the tool returns status: "initiated". This means the transfer was started, not that it connected. Do not tell the caller the transfer succeeded in that case.

Passing custom SIP headers

When using SIP transfers, you can attach custom SIP headers with the headers parameter on call_transfer. For details, see Pass Custom SIP Headers on Voice Transfer.

Errors

Code	Meaning
`INVALID_INPUT`	The call arguments did not match the tool’s schema.
`MISSING_PHONE_NUMBER`	PSTN transfer, but no valid PSTN number is configured for the project.
`MISSING_SIP_TARGET`	SIP transfer, but no destination could be resolved.
`INVALID_SIP_URI`	The transfer method is `invite` and the destination is not a valid `sip:` or `sips:` URI.
`SIP_ROUTING_FAILED`	Dynamic routing could not be validated for this call. The transfer was not attempted.
`SIP_TRANSFER_ID_INVALID`	The authored SIP destination could not be resolved or failed safety checks. The transfer was not attempted.
`MISSING_SIP_URI_HEADER` / `INVALID_SIP_URI_HEADER`	A required header value for the SIP URI is missing or invalid for this call.
`VOICE_TRANSFER_UNSUPPORTED`	The current voice channel does not support transfers.
`VOICE_TRANSFER_DISPATCH_UNAVAILABLE`	The voice session that owns the call is not available.
`TRANSFER_DISPATCH_FAILED`	The voice gateway failed to dispatch or observe the transfer.

Examples

Example 1: Transfer to a configured SIP destination Use a project-configured SIP destination when all calls transfer to the same endpoint.

AGENT: transfer_my_call

TOOLS:
  call_transfer(
      callTransferType: string,
      message: string
  ) -> object

FLOW:
  start -> handoff

  handoff:
    CALL:
      call_transfer(
        callTransferType: "sip",
        message: "Connecting you now."
      )
    THEN: COMPLETE
    ON_FAILURE: transfer_failed

  transfer_failed:
    RESPOND: "I'm sorry, I couldn't connect you right now. Please try again later."
    THEN: COMPLETE

The destination is the SIP target from Project Settings. Example 2: Route calls dynamically Use a workflow to determine the transfer destination at runtime. This approach is useful when calls must be routed to different queues or contact-center destinations based on customer attributes such as region, language, or business unit.

AGENT: transfer_my_call

TOOLS:
  call_transfer(callTransferType: string, sipTransferId: string, message: string) -> object
    params:
      sipTransferId:
        default_source: config
        template: "sip:{{route.vdn}}@{{route.ip}}:{{route.port}};user=phone?User-to-User={{sip.user-to-user}}"
        approved_authorities:
          - "sip:421003@172.0.41.7:5060"
          - "sip:421004@172.0.41.7:5060"
          - "sip:421005@172.0.41.7:5060"
          - "sip:5210[0-9][0-9]@172.0.41.7:5060"
    confirm: never

FLOW:
  resolve_destination -> transfer_step

  resolve_destination:
    REASONING: false
    RESOLVE_SIP_DESTINATION:
      FROM_WORKFLOW: "lookup_vdn_by_region_language"
    THEN: transfer_step
    ON_FAILURE: transfer_failed

  transfer_step:
    CALL:
      call_transfer(
        callTransferType: "sip",
        message: "Connecting you to the right desk."
      )
    THEN: COMPLETE
    ON_FAILURE: transfer_failed

  transfer_failed:
    RESPOND: "I'm sorry, I couldn't connect you right now. Please try again later."
    THEN: COMPLETE

Example 3: Transfer to a PSTN number

TOOLS:
  call_transfer(
      callTransferType: string,
      message: string
  ) -> object

FLOW:
  transfer_step:
    CALL:
      call_transfer(
        callTransferType: "pstn",
        message: "Transferring you to our support line."
      )
    THEN: COMPLETE
    ON_FAILURE: transfer_failed

The number dialed is the PSTN transfer number set in Project Settings. You cannot pass a phone number in the call.

`call_transfer` vs `ESCALATE`

call_transfer is an immediate, stateless telephony handoff with no record kept once the call leaves. ESCALATE, on the other hand, creates a trackable HumanTask (queueing, priority, SLA, optional ITSM integration) and works the same way for both voice and digital channels.

Feature	`call_transfer`	`ESCALATE`
What it does	Transfers the active voice call directly.	Creates and tracks a human escalation task.
Mechanism	Direct SIP REFER / PSTN dial. No task record is created.	Creates a HumanTask with assign/claim/resolve lifecycle, SLA tracking, and optional ITSM ticket creation.
Channels	Voice only.	Voice, chat, email, messaging, and campaign channels.
Task lifecycle	Does not manage human task lifecycle.	Creates, tracks, and completes human tasks.

Get started

Build

Test and evaluate

Deploy

Analytics and insights

References

Inbuilt tool - call_transfer

When to use

Declare the tool

Parameters

Where the destination comes from

How it works

Passing custom SIP headers

Errors

Examples

`call_transfer` vs `ESCALATE`

​When to use

​Declare the tool

​Parameters

​Where the destination comes from

​How it works

​Passing custom SIP headers

​Errors

​Examples

​call_transfer vs ESCALATE

When to use

Declare the tool

Parameters

Where the destination comes from

How it works

Passing custom SIP headers

Errors

Examples

`call_transfer` vs `ESCALATE`