Dynamic Transfers

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.

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:

1
[
2
  {
3
    "phone_number": "+14155551234",
4
    "department": "Sales",
5
    "agent_name": "John Smith"
6
  },
7
  {
8
    "phone_number": "+15100055555",
9
    "department": "Engineering",
10
    "agent_name": "Jane Doe"
11
  },
12
]

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

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:

1
[
2
  {
3
    "phone_number": "+14155551234",
4
    "agent_name": "Primary Agent",
5
    "priority": 1
6
  },
7
  {
8
    "phone_number": "+14155555678",
9
    "agent_name": "Backup Agent",
10
    "priority": 2
11
  },
12
  {
13
    "phone_number": "+14155559999",
14
    "agent_name": "Overflow Queue",
15
    "priority": 3
16
  }
17
]

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:

1
{
2
  "customer_id": "{customer_id}",
3
  "issue_type": "{issue_type}"
4
}

Response:

1
[
2
  {
3
    "phone_number": "+14155552345",
4
    "agent_name": "Sarah Johnson",
5
    "department": "Technical Support",
6
    "specialty": "billing",
7
    "available": true
8
  },
9
  {
10
    "phone_number": "+14155556789",
11
    "agent_name": "Mike Chen",
12
    "department": "Technical Support",
13
    "specialty": "account_access",
14
    "available": true
15
  },
16
  {
17
    "phone_number": "+14155553456",
18
    "agent_name": "Lisa Park",
19
    "department": "Sales",
20
    "specialty": "upgrades",
21
    "available": true
22
  }
23
]

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