Handoff management

Overview

For situations that your AI Agent can’t handle, you can configure procedures for handing end users off to live agents. Configure different Handoffs to suit different situations for your end users, and build your handoff content using modular blocks to ensure a smooth experience.

Limitations

Handoff management has the following constraints:

• Maximum active handoffs: You can have up to five active handoffs at a time.
• Variable scope: Variables used in handoff blocks only work within structured content and are separate from information collected through Actions.

Use cases

Handoffs help you route end users to human agents when your AI Agent can’t resolve an inquiry.

• Live agent escalation: Transfer end users to human agents in real-time via chat or call transfer.
• Asynchronous follow-up: Create tickets or cases for agent follow-up via email.
• Off-hours handling: Provide alternative paths when human agents are unavailable.
• Error recovery: Define fallback behavior when handoff attempts fail.
• Context-based routing: Route end users to different handoffs based on conversation context or variables.

Capabilities & configuration

Handoffs provide flexible options for routing end users to human agents across different channels and platforms.

Just choosing the right handoff method?

Use this table to choose the right platform-specific handoff block based on the channel and whether the handoff should result in real-time or asynchronous agent follow-up. The table focuses on supported handoff blocks for Zendesk and Salesforce. For other platforms, the methods reflect common patterns that assume support for email-based interactions.

To further refine your flow—such as routing based on variables, updating existing tickets, or triggering fallback logic—add supporting blocks like conditionals, HTTP requests, or custom routing logic as needed. For a complete list of all available handoff blocks, see Implementation & usage.

Handoff types

Your AI Agent handles different situations that might require handoffs differently:

• Handoffs to live agents

  On the Ada dashboard, when you go to Config > AI AGENT > Handoffs, on the Handoffs tab, you can view and modify handoffs to live agents.

  When your AI Agent detects it needs to hand an end user off to a live agent, it chooses from these configured handoffs based on the name and description you provide (e.g., you might use one handoff for subscription renewals and another for returns).

• Fallback handoffs

  Fallbacks are used when a handoff can’t proceed as expected. There are two main types:

  • Off-Hours: Used when an end user requests a synchronous handoff (like live chat or Messaging with Zendesk Chat or Salesforce Chat handoffs) but no human agents are online. This is configured in the handoff platform (e.g., Zendesk Chat operating hours). Off-hours typically don’t apply to asynchronous handoffs like ticket creation, and they aren’t relevant for Email. In channels with asynchronous handoffs — for example, Voice, or Chat with Zendesk Messaging handoffs — customers can simulate on-hours vs. off-hours behavior by combining the Scheduled block with conditionals.
  • Error Fallback: Used when an error occurs during a handoff attempt, such as when your AI Agent tries to transfer to a live agent or make an API request and something goes wrong. Error fallbacks apply across all channels, including Voice and Email.
  Depending on the features your organization has enabled, you may see more preconfigured handoff types in your dashboard. For more information, reach out to your Ada team.

Variables in Handoffs

You can create Variables to capture or set a piece of information, so you can use the value saved in the variable later. Variables are useful for:

• Referring to basic pieces of information in a conversation (e.g., get the end user’s name so you can refer back to it later)
• Passing metavariables through handoffs to provide human agents with information about the end user (e.g., their email address)
• Dynamically collecting information with auto-capture variables (e.g., if you create an auto-capture variable for the end user’s account number, your AI Agent will check to see if it has that information, and if not, it will ask the end user autonomously)

You can use the same variable in other places where you can use blocks in your AI Agent, too—your AI Agent will know not to ask for the same piece of information twice, and if you do want it to ask twice, it will know to always use the newest value.

As a best practice, when you’re using a variable to repeat a piece of information in text (e.g., if you’re repeating the end user’s name), make sure you set fallback values so that if the variable is not set, your AI Agent can still have something to say.

Quick start

Create a Handoff in a few steps.

For detailed instructions, see Implementation & usage.

Implementation & usage

Create and manage Handoffs and their content.

Create or edit a Handoff

Every piece of Handoff content contains default content. You can edit that content directly, or you can edit it by adding or removing blocks.

To create or edit a Handoff:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs.

2. Choose the type of handoff you want to configure.

   • To create or edit a regular handoff, go to the Handoffs tab. Then, click New Handoff, or click an existing handoff type to edit it.

     1. Under Identify this Handoff, fill in information about the handoff under Name and Description.

        Your AI Agent will use the information you enter here when it’s reasoning through when it’s appropriate to trigger this handoff.

     2. If required, you can restrict Handoffs to certain users, based on information your AI Agent collects about your users and saves in variables.
     You can only use variables your AI Agent can collect through your browser, or that you collect in a block and allow to be available outside of the structured content the block is in. You can’t use variables your AI Agent collects using Actions.

     • To make the handoff available to all users, select Everyone.

     • To restrict the handoff to certain users, select Based on the following rules. A section expands where you can enter the logic your AI Agent will use to decide whether to serve the handoff.

       1. Under Where, in the Choose a variable list, select a variable.
       2. In the next dropdown, select an operator so you can define a relationship between the variable and the value you want to target.

       Understand comparison operators

       Comparison operators are logic statements that tell your AI Agent to match end user information that’s captured in the variable you’re using. The available operators vary based on the variable type you’re using:

       Operator	Variable types	Description
       Begins With	- All text variables (including phone and email)	Match information in the variable that begins with certain text (partial match).
       Ends With	- All text variables (including phone and email)	Match information in the variable that ends with certain text (partial match).
       Contains	- All text variables (including phone and email) - List variables	Match information in the variable that contains certain text in any position (partial match).
       Is	- All text variables (including phone and email) - Number variables	Match information in the variable that equals specific text exactly (exact match).
       Is Not	- All text variables (including phone and email) - Number variables	Match information in the variable that doesn’t equal specific text exactly (exact match).
       Is Not Set	- All text variables (including phone and email) - Number variables - List variables	Match if there is no information contained in the variable.
       Is Set	- All text variables (including phone and email) - Number variables - List variables	Match if there is any information contained in the variable.
       Greater Than	- Number variables	Match if the information in the variable is greater than a specific value.
       Less Than	- Number variables - List variables	Match if the information in the variable is less than a specific value.
       Is True	- Yes/No variables	Match if the information in a variable is Yes (or True).
       Is False	- Yes/No variables	Match if the information in a variable is No (or False).
       Does Not Contain	- List variables	Match if none of the selected items contains this value.
       Is Equal To	- List variables	Match if the end user selected a particular number of options in a List Option block.
       Is Greater Than	- List variables	Match if the end user selected more than a particular number of options in a List Option block.
       Is Less Than	- List variables	Match if the end user selected fewer than a particular number of options in a List Option block.

       3. In the Value field, enter or select a value for the variable that you want to use to target users.
       4. If required, add additional conditions.

       • To add a new top-level condition, click Add .

         If you’re adding your first additional top-level condition, in the dropdown that appears, choose And or Or as the operator for all of your top-level conditions.

       • To create or add to a group of conditions, click the Add to group icon beside a condition you want to include in the group.

         If you’re creating a group, in the dropdown that appears, choose And or Or as the operator for all of the conditions in that group.

   • To edit an off-hours handoff, go to the Off hours tab. Then, click a handoff situation to edit it.

3. Use blocks to build your handoff content. You can:

   • Drag blocks from the block drawer on the right side of your screen into your handoff content, then add content in them
   • Edit content in existing blocks directly
   • Click the Delete icon on a block to remove it

   Depending on the way your AI Agent is configured, the blocks available to you may vary:

   Block	Description
   Text block	Delivers simple text messages to customers. Each block appears as a single chat bubble.
   Link block	Adds links to direct customers to websites or communication methods.
   Capture block	Prompts customers for information and saves it as a variable for use in other blocks.
   Set Variable block	Automatically defines variables that you can use in other blocks.
   Conditional block	Targets specific content to different customers depending on variables associated with them.
   Request block	Makes an API call and saves all or part of the response as a variable.
   List Option block	Offers customers a list of selectable items and saves their selection as a variable.
   Sign In and Sign Out blocks	Authorizes customers by asking them to sign in to their account.
   Fetch Chat Metadata block	Adds the chat transcript and/or customer information from a conversation as variables.
   Email block	Hands customers off via email with customizable fields.
   Scheduled block	Sets days of the week and time ranges for different responses based on your schedule.
   File Upload block	Allows customers to upload files directly. The uploaded file attaches to the support ticket.

   Integration-based handoffs

   You can also hand off customers using third-party integrations:

   Integration	Description
   Salesforce handoffs	Hands off customers using Salesforce Chat or Salesforce Messaging.
   Zendesk handoffs	Hands off customers using Zendesk Chat, email tickets, or Zendesk Support.

4. At the bottom of the screen, click Save. Your AI Agent saves your changes.

Manage Handoff versions

Your AI Agent saves a history of all edits you have made to your Handoff content over the last 30 days. You can revert your changes to your Handoff content back to any of these saved versions.

To view and manage Handoff versions:

1. On the Ada dashboard, go to Config > AI AGENT > Handoffs, then on the Handoff tab, open the handoff content you want to manage versions for.
2. At the top of the page, you can see when the handoff content was last edited. Click that text to open a pane that contains a list of versions of the handoff content over the last 30 days. You can click a version to see the handoff content at that time.
3. Optionally, for significant versions, you can add a name and description for future edits. To do this, hover over the version, click the More options button that appears, filling in the Version Title and Description fields as required, then clicking Save.
4. To revert to a previous version of your handoff content, select the version you want to go back to. Then, at the top of the page, click Restore Version. Review your changes to ensure you’re not reverting anything you want to keep, then click Save to save your reverted changes.

Related features

• Handoffs: Learn about Handoff concepts and architecture.
• Zendesk integration: Configure handoffs to Zendesk.
• Salesforce integration: Configure Handoffs to Salesforce Chat and Salesforce Messaging.
• Actions: Automate tasks within conversations using Actions.
• Variables: Capture and use information across conversations using Variables.