Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.asapp.com/llms.txt

Use this file to discover all available pages before exploring further.

A Handoff defines how and when GenerativeAgent routes a conversation to a human agent queue. Unlike a raw system transfer, a Handoff is availability-aware: it resolves agent availability and provides GenerativeAgent with the appropriate instructions for the current state, covering both the agent-available and agent-unavailable cases. Handoffs can be triggered from a Topic article or from inside a Task. Use a Handoff any time a conversation should reach a human agent queue.

​
How Handoffs Work

When a Topic article with an associated Handoff is relevant to the conversation, the Handoff provides GenerativeAgent with the appropriate instructions. If agents are available, GenerativeAgent receives the agent-available block (e.g., collect context and confirm the transfer). If agents are not available, GenerativeAgent receives the agent-unavailable block (e.g., inform the caller of business hours, offer a callback). Availability is resolved by the Handoff before GenerativeAgent is invoked. GenerativeAgent does not check the schedule itself. It only sees the instruction set for the current availability state. You can configure the transfer destination for each Handoff and decide which Handoff to associate with each Topic article.

​
Configure Handoffs

To create a handoff, select Handoffs in the left-hand menu of the AI Console. Then click Create Handoff and follow the steps below.
Handoff configuration showing destination JSON, agent available instructions, and agent unavailable instructions
1

Define Handoff Details

Provide a name and description for the handoff. The description should help GenerativeAgent understand when this handoff should be triggered.Click Generate handoff to create it.
2

Write Agent Available Instructions

These instructions tell GenerativeAgent what to do when the destination queue has agents available. You can instruct GenerativeAgent to:
  • Transfer immediately
  • Ask the caller for confirmation before transferring
  • Collect specific information before the transfer
The instructions reference a proxy function named handoff_[handoff_name] (e.g., a handoff named “Billing Support” produces the function handoff_billing_support). You do not need to create this function manually; it is generated from the handoff configuration.
3

Write Agent Unavailable Instructions

These instructions tell GenerativeAgent what to say when agents are not available. For example:“I apologize, there are no agents available at this time. Please try calling back another time. I would be happy to help you with anything else. Is there anything I can assist you with now?”
4

Configure the Handoff Destination

The destination defines where the conversation will be routed and when agents are available. Configure it as a JSON object.The destination JSON is an array of queue objects. The AI Console provides example templates via the Examples dropdown.
Example: Queue open 24/7
[
  {
    "name": "Billing Support",
    "type": "Agent_queue",
    "enabled": true,
    "open_24": true,
    "timezone": "America/New_York",
    "transfer_function_name": "default_transfer"
  }
]
Example: Queue with business hours
[
  {
    "name": "Sales Queue",
    "type": "Agent_queue",
    "enabled": true,
    "open_24": false,
    "weekly_hours": {
      "mon": [{"start": "09:00", "end": "17:00"}],
      "tue": [{"start": "09:00", "end": "17:00"}],
      "wed": [{"start": "09:00", "end": "17:00"}],
      "thu": [{"start": "09:00", "end": "17:00"}],
      "fri": [{"start": "09:00", "end": "17:00"}]
    },
    "timezone": "America/New_York",
    "transfer_function_name": "transfer_to_sales"
  }
]
Example: Full configuration with date exceptions and language support
[
  {
    "name": "Premium Support",
    "type": "Agent_queue",
    "enabled": true,
    "open_24": false,
    "weekly_hours": {
      "mon": [
        {"start": "09:00", "end": "12:00"},
        {"start": "13:00", "end": "17:00"}
      ],
      "tue": [{"start": "09:00", "end": "17:00"}],
      "wed": [{"start": "09:00", "end": "17:00"}],
      "thu": [{"start": "09:00", "end": "17:00"}],
      "fri": [{"start": "09:00", "end": "17:00"}],
      "sat": [{"start": "10:00", "end": "14:00"}]
    },
    "date_exceptions": {
      "2026-12-25": {"closed": true},
      "2026-07-04": {"open_24": true}
    },
    "timezone": "America/Los_Angeles",
    "supported_channel_types": ["voice", "chat"],
    "supported_languages": ["en", "es"],
    "transfer_function_name": "transfer_to_premium"
  }
]

​
Destination fields

FieldRequiredDescription
nameYesThe name of the queue.
typeYesThe type of destination. Use "Agent_queue".
enabledYesWhether this destination is active.
open_24YesIf true, the queue is always available. If false, you must provide weekly_hours.
timezoneYesIANA timezone string (e.g., America/New_York, America/Los_Angeles).
transfer_function_nameYesThe system transfer function to call when this destination is used. Must match an existing system transfer function.
weekly_hoursIf open_24 is falsePer-day availability. Each weekday (mon through sun) maps to an array of {"start": "HH:MM", "end": "HH:MM"} intervals. Multiple intervals per day are supported for split shifts. Days not listed are treated as closed.
date_exceptionsNoOverride specific dates. Keyed by YYYY-MM-DD. Each value is one of: {"closed": true}, {"open_24": true}, or {"intervals": [{"start": "HH:MM", "end": "HH:MM"}]}.
supported_channel_typesNoArray of channel types this destination supports ("voice", "chat"). Omitted means all channels.
supported_languagesNoArray of BCP 47 language codes (e.g., "en", "es"). Omitted means all languages.
The transfer_function_name must reference a system transfer function that already exists in your configuration. This function controls what parameters (SIP headers, transfer variables, etc.) are passed to your telephony or contact center system during the transfer. See System Transfer Functions for setup details.
When the handoff configuration is saved, the system validates the destination JSON schema and confirms the referenced system transfer function exists.
Click Save to save the handoff configuration.

​
Associate Handoffs with Topics

After creating a Handoff, you need to associate it with the relevant Topics in your knowledge base. This is what connects caller intent to a routing destination. When GenerativeAgent matches a conversation to a Topic that has an associated Handoff, it evaluates whether to escalate based on the conversation context and the Handoff’s conditions. Each Topic can have one or more Handoff scenarios. For example, a “Billing inquiry” Topic might route to a “Billing Support” queue during business hours and to a “General Support” queue after hours. To associate a handoff with a topic:
  1. Navigate to Knowledge in the left-hand menu of the AI Console.
  2. Select a topic from the list of topics.
  3. In the topic details, scroll down to the Handoff scenarios section.
  4. Click on Add handoff and select the handoff you want to associate with the topic.
KB Topic detail showing Handoff scenarios section with an associated handoff
If a Topic and its associated Handoff are retrieved during a conversation but the Handoff is not triggered when expected, add additional instructions to the Topic to reinforce when that Handoff should be used. The Topic’s instructions help GenerativeAgent decide which resolution path to take for a given scenario.

​
Handoffs and System Transfers

While Handoffs and system transfers may look similar, they operate at different layers. Handoffs are the right tool any time a conversation should reach a human agent queue, whether triggered from a Topic article or from inside a Task. The Handoff resolves availability, provides GenerativeAgent with the appropriate instructions, and initiates the transfer using the associated system transfer function. System transfers are the underlying mechanism that defines what gets sent during a transfer. The transfer_function_name on a Handoff destination points to a system transfer function, which controls the parameters passed to the receiving system (e.g., SIP headers, output context on a call transfer). System transfers are associated with Handoffs. Builders should reach for Handoffs to initiate any transfer to a human agent rather than adding system transfer functions as a standalone escalation path.

​
When to Use Handoffs

Use handoffs when you want to ensure that customers receive timely and relevant assistance from human agents when GenerativeAgent escalates their conversations. Handoffs are particularly useful in scenarios where:
  • The customer’s issue is complex and requires human judgment or empathy.
  • The customer requests to speak with a human agent.
  • GenerativeAgent identifies that it cannot assist the customer effectively and determines that a handoff is necessary.
Handoffs should not be used for the following scenarios:
  • When the customer’s issue requires an API call before the handoff (such as fetching data like account status, etc). In this case, you can use a Task to perform the API call and then transfer the conversation to a human agent with the relevant information.