***
title: Dynamic Transfers
slug: dynamic-transfers
subtitle: Using Custom Variables for Call Transfers and Messages
---------------------
For clean Markdown of any page, append .md to the page URL. For a complete documentation index, see https://docs.synthflow.ai/llms.txt. For full documentation content, see https://docs.synthflow.ai/llms-full.txt.
In some situations, you may not know in advance which phone number you need to transfer a call to, or what message should be played to the user during the transfer. **Custom variables** let you handle these dynamic scenarios easily.
Looking for other transfer types? See the [Call Transfers overview](/call-transfers) for phone number (TEL) and SIP transfer options.
Learn more about how custom variables work
[here.](/custom-variables)
## Creating custom variables
Custom variables can be created in different situations:
* **Injected before the call starts** using a **pre-call webhook**
* **Collected during the call** as a result of a **custom action**.
## Returning Phone Numbers from Custom Actions
Custom actions can now return phone numbers dynamically that can be used for call transfers. When your custom action returns a response containing a phone number, you can reference it in your transfer action using template syntax.
### How it works:
1. Your custom action makes an API call which returns a list of potential transfer targets.
2. The action response is available to the agent, which prompts the user to select their desired transfer target.
3. The agent triggers a transfer to the target using the target variable.
### Custom Action API Response Format Example:
```json
[
{
"phone_number": "+14155551234",
"department": "Sales",
"agent_name": "John Smith"
},
{
"phone_number": "+15100055555",
"department": "Engineering",
"agent_name": "Jane Doe"
},
]
```
### Using the Returned Phone Number:
When your custom action returns an array of potential transfer targets, the agent can intelligently select the appropriate one based on the conversation context.
#### Setting up the Actions:
**In the Custom Action:**
1. Configure your custom action to call your API endpoint
2. In the "Available Action Results" section of the custom action, select the following fields:
* Enable `status` (the action status)
* Enable `results` (the results object)
* Enable `results.data` (the array containing your transfer targets)
**In the Transfer Action:**
1. In the transfer action's phone number field, enter a variable name like `phone_number`
The agent will have access to the full array of transfer options from the custom action and will intelligently select the appropriate phone number based on the user's request during the conversation. The selected phone number will be passed as the `phone_number` argument to the transfer tool.
For example, if the user says "transfer me to sales", the agent will look through the `results.data` array, identify the sales department entry, and use that phone number for the transfer.
The system will automatically detect this as a dynamic transfer and extract the phone number at runtime.
## Using a custom variable to route the call
### Method 1: Using Pre-defined Variables
1. Create a new transfers action
2. Instead of entering a phone number to transfer, click variables and select the variable you created which represents a phone number.
### Method 2: Using Custom Action Results (Dynamic Transfer)
1. Create a custom action that returns a phone number
2. In your transfer action, reference the returned value using template syntax:
* For example: `{results.data.phone_number}`
* The system automatically detects this pattern and configures the transfer as dynamic
* The phone number is extracted and normalized at runtime
## Using Custom Variables in Spoken Messages during the transfer
You can also use custom variables to control what is spoken to **the transfer target** or **the customer** during the transfer.
Within a **Call Transfer** action:
1. Open the text fields for the messages you want to customize.
2. Insert your variables using **curly braces **`{ }` — for example:
```
Transferring you to {team_name}.
```
This will dynamically replace `{team_name}` with the value of your variable during the call.
## **Example Use Cases**
| Use Case | Description |
| -------------------------- | ---------------------------------------------------------- |
| **CRM-based routing** | Fetch the assigned account manager's number from your CRM |
| **On-call routing** | Query your scheduling system for the current on-call staff |
| **Tier-based escalation** | Route VIP customers to senior agents automatically |
| **Location-based routing** | Transfer to the nearest office based on caller location |
| **Skills-based routing** | Match caller needs to agent expertise in real-time |
| **Load balancing** | Distribute calls across available agents |
***
## Handling Transfer Failures
When using dynamic transfers, your custom action can handle failures gracefully:
### Fallback Destinations
Return multiple potential destinations from your API, ordered by priority:
```json
[
{
"phone_number": "+14155551234",
"agent_name": "Primary Agent",
"priority": 1
},
{
"phone_number": "+14155555678",
"agent_name": "Backup Agent",
"priority": 2
},
{
"phone_number": "+14155559999",
"agent_name": "Overflow Queue",
"priority": 3
}
]
```
The agent can attempt transfers in priority order if earlier attempts fail.
### No Available Agents
When your API returns no available destinations, the agent can:
* Offer to take a message
* Schedule a callback
* Provide alternative contact methods (email, chat)
* Transfer to a general queue
Configure this behavior in your agent's prompt to handle the "no results" case gracefully.
## Practical Example: Dynamic Customer Support Routing
Here's a complete example of using a custom action to dynamically route calls:
### Step 1: Custom Action Configuration
Create a custom action that queries your CRM or routing system for available agents:
**Endpoint:** `https://api.yourcompany.com/get-available-agents`
**Request:**
```json
{
"customer_id": "{customer_id}",
"issue_type": "{issue_type}"
}
```
**Response:**
```json
[
{
"phone_number": "+14155552345",
"agent_name": "Sarah Johnson",
"department": "Technical Support",
"specialty": "billing",
"available": true
},
{
"phone_number": "+14155556789",
"agent_name": "Mike Chen",
"department": "Technical Support",
"specialty": "account_access",
"available": true
},
{
"phone_number": "+14155553456",
"agent_name": "Lisa Park",
"department": "Sales",
"specialty": "upgrades",
"available": true
}
]
```
### Step 2: Action Configuration
**Custom Action:**
1. Configure the custom action to call the API endpoint above
2. In the custom action's "Available Action Results" section:
* Select `status`, `results`, and `results.data`
**Transfer Action:**
1. In the transfer action's phone number field, enter `phone_number` as the variable name
### Step 3: How It Works
During the call, when a customer requests a transfer:
* If they say "I need help with my bill", the agent will select Sarah Johnson
* If they say "I can't log in", the agent will select Mike Chen
* If they say "I want to upgrade my plan", the agent will select Lisa Park
The agent intelligently matches the customer's request to the appropriate agent based on their specialty and department, then passes the selected phone number to the transfer action.
***
## Best Practices
1. **Always return availability status** - Include an `available` flag so the agent knows which destinations are actually reachable
2. **Provide context for the agent** - Include department, specialty, or other metadata to help intelligent routing
3. **Handle empty results** - Your API should return a clear response when no agents are available
4. **Use warm transfers for dynamic routing** - This allows retry logic if the first destination fails
5. **Log routing decisions** - Track which destinations are selected for analytics and optimization