Call Transfer

The Call Transfer tool lets your AI agent transfer an active telephony call to a phone number or SIP endpoint. You can configure a fixed destination, use a template from call context, or resolve the destination at transfer time by calling your HTTP endpoint.

Use this tool when the caller should speak to a human operator, department, escalation queue, support queue, or another phone system.

Supported providers

Call transfer is available for telephony calls on Twilio, Plivo, Telnyx, Cloudonix, and Asterisk ARI.

How call transfer works

When the LLM decides a transfer is needed, it calls the Call Transfer tool. Talkr resolves the destination, validates the transfer setup, and then starts the provider transfer.

For a successful transfer:

1. The agent calls the Call Transfer tool.
2. Talkr resolves the destination from either static configuration or a dynamic HTTP resolver.
3. Talkr optionally plays a pre-transfer message to the caller.
4. Talkr starts dialing the destination through the telephony provider.
5. The caller hears hold music while the destination leg is connecting.
6. If a handoff message is configured, the person who answers hears it before being connected — see Handoff message below.
7. When the destination answers, Talkr connects the caller and ends the AI agent's involvement.

Destination source

You must choose one destination source for each Call Transfer tool.

Static / Template

Use this when the transfer destination is already known before the transfer happens.

Static destinations can be:

• A fixed E.164 phone number, such as +1234567890
• A SIP endpoint, such as PJSIP/1001
• On Asterisk ARI, a dialplan destination such as Local/support@internal — see Asterisk ARI
• A template value from context, such as {{initial_context.transfer_destination}}

This is the simplest option for fixed support lines, fixed departments, or cases where the destination is provided before the call starts.

Dynamic HTTP Resolver

Use this when the destination must be decided during the conversation.

Talkr sends a POST request to your resolver endpoint before starting the transfer. Your endpoint returns the destination and may return a custom message to play before dialing.

Common use cases:

• Route by region, timezone, or language
• Look up the right account team in your customer system
• Route by customer tier or account status
• Route by issue type, language, or department
• Use business logic from your backend instead of hardcoding numbers in Talkr

Dynamic resolver request

The resolver request body is a flat JSON object.

Talkr builds it from:

• LLM parameters: values the agent extracts from the conversation when it calls the transfer tool
• Preset parameters: values Talkr injects from fixed values or templates such as {{initial_context.account_id}} or {{gathered_context.billing_issue_type}}

If both define the same key, preset parameters take precedence.

Example request body:

{
  "account_id": "acct_123",
  "plan": "enterprise",
  "billing_issue_type": "invoice_dispute"
}

Dynamic resolver response

Your resolver must return a JSON object with transfer_context.destination.

transfer_context.custom_message is optional.

{
  "transfer_context": {
    "destination": "+1234567890",
    "custom_message": "Please wait while I connect you with our enterprise billing team."
  }
}

Field behavior:

• destination: Required. E.164 phone number or SIP endpoint.
• custom_message: Optional. If returned, this message is played before the provider transfer starts.

If the resolver fails, times out, returns invalid JSON, or omits transfer_context.destination, the transfer fails gracefully and the agent can continue handling the caller.

Dynamic resolver configuration

When using a dynamic resolver, configure:

• Resolver URL: HTTPS or HTTP endpoint Talkr calls with POST
• Resolver Timeout: How long Talkr waits for the resolver response
• Resolver Wait Message: Optional message spoken while Talkr waits, such as "One moment while I find the right team."
• LLM Parameters: Values the agent should extract from the conversation, such as billing_issue_type or requested_department
• Preset Parameters: Values injected by Talkr from context or fixed values
• Custom Headers: Static headers sent to your resolver endpoint
• Credential: Optional saved credential used to authenticate the resolver request

Pre-transfer messages

Call Transfer supports a common pre-transfer message setting for both static and dynamic destinations.

For static transfers:

1. Talkr resolves the static or template destination.
2. Talkr plays the configured pre-transfer message, if any.
3. Talkr starts the provider transfer.

For dynamic transfers:

1. Talkr may play the resolver wait message while calling your resolver.
2. If the resolver returns custom_message, Talkr plays that message.
3. If the resolver does not return custom_message, Talkr uses the configured pre-transfer message.
4. Talkr starts the provider transfer.

Resolver custom_message overrides the configured pre-transfer message for that transfer attempt.

Handoff message

The pre-transfer message plays to the caller. The handoff message is different: it plays to whoever answers the transfer, before they're connected with the caller — so a human agent doesn't have to ask the caller to repeat themselves.

Configure it as a template, the same way you'd configure a destination:

Caller: {{initial_context.caller_number}}. Reason: {{gathered_context.reason}}.

Leave it blank to keep today's generic "You have answered a transfer call. Connecting you now." line.

Supported on Twilio, Plivo, Telnyx, Cloudonix, and Asterisk ARI. On Asterisk ARI specifically, the message is synthesized with your organization's own configured TTS voice — on every other provider, it plays through that provider's own text-to-speech engine.

Transfer timeout

Transfer timeout is the maximum time Talkr waits for the destination to answer after the provider transfer starts.

This timeout applies to both static and dynamic transfers.

The resolver timeout is separate. It controls only how long Talkr waits for your HTTP resolver before dialing starts.

Destination formats

Twilio, Plivo, Telnyx, and Cloudonix

Use E.164 phone numbers:

+1234567890

The number must be reachable from your telephony provider.

Require acceptance (attended transfer)

By default the caller is connected the moment the destination picks up — whether or not that person can actually take the call. A supervisor in a meeting, a phone answered by the wrong person, a handset knocked off the hook: all become a connected caller.

Turn on Require acceptance and whoever answers is asked to confirm first:

• Press 1 — the caller is connected
• Press 2 — the transfer is declined, and Talkr moves on to the next fallback destination if you have configured one

Set a handoff message when you use this, and say what to press: "Incoming transfer from a customer with a billing question. Press 1 to accept, or 2 to decline." Without one, the person answering hears silence and has no idea a key is expected.

Fallback destinations

A single destination means a single attempt: if that line doesn't answer, the transfer fails and the agent tells the caller so.

Add fallback destinations to try others in order — the on-call number, then the backup queue — before giving up:

Destination           +15550100        the team's main line
Fallback 1            +15550111        on-call mobile
Fallback 2            Local/support@internal   the support queue

Each is tried for the same timeout, in the order listed, until one answers. Between attempts the caller hears a short spoken line so they know what's happening rather than sitting in silence.

Duplicate destinations are skipped, and a template that resolves to nothing — an unset context variable, say — drops out of the chain rather than becoming an empty dial attempt.

Fallbacks apply to static destinations. A dynamic resolver already decides routing at call time with live knowledge of who is available, so it is never second-guessed from a fixed list.

Asterisk ARI

Transfer to a single endpoint, to an extension, or into your dialplan:

PJSIP/1001                 a specific endpoint
1001                       an extension (dialled on PJSIP)
Local/support@internal     your dialplan — a queue, ring group or hunt list
Local/sales@internal/n     the same, without local channel optimisation

A destination that starts with a channel technology — PJSIP/, SIP/, Local/, IAX2/, DAHDI/ — is passed to Asterisk exactly as written. Anything else is treated as an extension and dialled on PJSIP.

Example: route enterprise billing calls

Use this setup when the agent identifies a billing issue and your backend decides whether to route the caller to standard billing, enterprise billing, or collections.

Configure LLM parameters:

[
  {
    "name": "billing_issue_type",
    "type": "string",
    "description": "The billing issue the caller needs help with, such as invoice_dispute, payment_failed, refund_request, or plan_change.",
    "required": true
  },
  {
    "name": "requested_department",
    "type": "string",
    "description": "The department the caller is asking for, if they explicitly mention one.",
    "required": false
  }
]

Configure preset parameters:

[
  {
    "name": "account_id",
    "type": "string",
    "value_template": "{{initial_context.account_id}}",
    "required": true
  },
  {
    "name": "plan",
    "type": "string",
    "value_template": "{{initial_context.plan}}",
    "required": true
  }
]

Your resolver receives:

{
  "billing_issue_type": "invoice_dispute",
  "requested_department": "billing",
  "account_id": "acct_123",
  "plan": "enterprise"
}

Your resolver returns:

{
  "transfer_context": {
    "destination": "+18005550199",
    "custom_message": "Please wait while I connect you with our enterprise billing team."
  }
}

Best practices

• Keep resolver latency low. Aim for 2-3 seconds.
• Use a resolver wait message if the resolver may take noticeable time.
• Send only the parameters your resolver needs.
• Prefer preset parameters for values already available in initial_context or gathered_context.
• Make LLM parameter descriptions explicit so the agent knows what to extract.
• Test both successful transfer and resolver failure paths before going live.
• Keep destination validation and routing logic in your backend when routing depends on account data or business rules.

Troubleshooting

The transfer tool is not called

Check that the tool is attached to the correct node and that the node prompt clearly tells the agent when to transfer.

Static transfer fails with no destination

Static mode requires a configured destination. Use a fixed destination or a template that resolves to a non-empty value.

Dynamic transfer fails before dialing

Check the resolver response. It must include:

{
  "transfer_context": {
    "destination": "+1234567890"
  }
}

Also verify the resolver URL, authentication headers, credential, and timeout.

Resolver receives missing parameters

Confirm the parameter is configured as either:

• an LLM parameter, if the agent should extract it from the conversation
• a preset parameter, if Talkr should inject it from context

For known context values, prefer preset parameters like {{initial_context.account_id}} or {{gathered_context.billing_issue_type}}.

Destination does not connect

Verify that the phone number or SIP endpoint is valid and reachable from the configured telephony provider.