> For the complete documentation index, see [llms.txt](https://docs.maiagent.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/human-handoff.md).

# Human Agent Handoff Settings

Configure when an Agent hands conversations over to human support: handoff conditions, messages and the queue experience, service hours, assignment modes and agent availability, and internal notificat

When a user's question exceeds what the Agent can handle (for example, an explicit request for human assistance or a question involving sensitive information), the platform can transfer the conversation to human support. A support agent then takes over and replies from the console. This page explains how to enable and configure handoff. For daily support operations, see [Taking Over and Replying as a Human Agent](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/human-handoff-operations.md).

{% hint style="info" %}
**Setup guide**: This page covers one step in configuring a conversation platform. For the complete text support launch process, see [Text Support: From Setup to Launch](https://docs.maiagent.ai/maiagent-user-guide/en/serve/text-service.md).
{% endhint %}

{% hint style="info" %}
All conversation platforms (Web, Internal, LINE, Microsoft Teams, and others) support human handoff. The difference is how users receive replies after handoff: Web and Internal platforms support real-time exchanges; the API platform has no chat interface, so you must develop your own frontend to receive replies.
{% endhint %}

## Where to Configure <a href="#where-to-configure" id="where-to-configure"></a>

Go to <mark style="color:blue;">Conversation Platforms</mark>, select the platform to enable, and switch to the <mark style="color:blue;">Human Handoff Settings</mark> tab. Turn on <mark style="color:blue;">Enable Human Handoff</mark> first to display the five configuration subtabs: <mark style="color:blue;">Handoff Conditions</mark>, <mark style="color:blue;">Handoff Messages</mark>, <mark style="color:blue;">Service Hours</mark>, <mark style="color:blue;">Assignment Settings</mark>, and <mark style="color:blue;">Notifications</mark>.

## Handoff Conditions <a href="#transfer-conditions" id="transfer-conditions"></a>

After you turn on <mark style="color:blue;">Enable Human Handoff</mark>, AI evaluates whether a handoff is needed whenever a user message arrives.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-0f4d50b4a7b8eb5c56d5a5ca9b36d1cac3b6d224%2Fhandoff-transfer-conditions.png?alt=media" alt="Handoff conditions settings screen"><figcaption><p>Handoff conditions: enable switch, evaluation model, and quick-insert conditions</p></figcaption></figure>

The evaluation is based on <mark style="color:blue;">Role Instructions</mark>: describe when a conversation should be transferred to a human, and the <mark style="color:blue;">Evaluation Model</mark> makes a decision using recent conversation messages (the number is controlled by <mark style="color:blue;">Reference Message Count</mark>).

The page provides four common conditions that you can insert into the role instructions with one click:

* **User requests a handoff**: The user explicitly asks to speak with a human support agent
* **Outside the knowledge base**: The question is outside the knowledge base and AI cannot answer effectively
* **Repeated questions and dissatisfaction**: The user repeats the same question and shows dissatisfaction
* **Sensitive information**: The conversation involves sensitive matters such as changes to personal information, billing, or legal issues

{% hint style="info" %}
In addition to automatic AI evaluation, support managers can manually take over any conversation in All Conversations at any time, regardless of the handoff conditions.
{% endhint %}

### Skip Handoff Evaluation <a href="#skip-handoff-check" id="skip-handoff-check"></a>

The <mark style="color:blue;">Skip Handoff Evaluation</mark> list below the role instructions specifies phrases that should not be evaluated for human handoff. When a customer's message matches a phrase in the list:

* The message is not evaluated for handoff, does not trigger a transfer, and consumes no evaluation Credits.
* AI replies as usual.
* In the internal conversation view, “Handoff evaluation skipped” appears below the message, along with the match type and the matching phrase.

For example, a LINE rich menu may include a “Human support service hours” button that sends this phrase when clicked. The evaluation model often interprets it as a handoff request. Adding “Human support service hours” to this list with an exact match prevents the button from triggering a handoff, so AI answers with the service hours directly. If the customer separately types “I want to speak to a human,” the role instructions still determine whether to transfer the conversation.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-cafd1c17d0cc871a6ececbcfc1787ab27a5e7cb2%2Fhandoff-skip-handoff-check.png?alt=media" alt="Handoff Conditions tab: the Skip Handoff Evaluation section below the role instructions, with Transfer me to a human added as an exact match"><figcaption><p>Skip Handoff Evaluation: located below the role instructions and saved with the page's Save button</p></figcaption></figure>

To configure it, click <mark style="color:blue;">Add Phrase</mark>, enter a phrase, select <mark style="color:blue;">Exact Match</mark> or <mark style="color:blue;">Contains</mark>, and click <mark style="color:blue;">Save</mark> at the bottom right of the page. Matching rules, phrase limits, and character limits are the same as for [Silent Skip](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/website.md#silent-skip-matching).

* When <mark style="color:blue;">Enable Human Handoff</mark> is off, this list is retained but has no effect (handoff evaluation is already disabled).
* To also prevent AI from responding to a phrase, use [Silent Skip](https://docs.maiagent.ai/maiagent-user-guide/en/build/choose-channel/web-chat/website.md#silent-skip-phrases) in the automatic reply settings instead. If the same phrase appears in both lists, AI neither replies nor transfers the conversation; only “Skipped according to rules” is displayed.

## Handoff Messages <a href="#transfer-messages" id="transfer-messages"></a>

You can customize the message sent to users at each stage of the handoff process (leave a field blank to send no message):

| Message                    | When It Is Sent                                     | Available Variables                                                  |
| -------------------------- | --------------------------------------------------- | -------------------------------------------------------------------- |
| Handoff notification       | When human handoff is triggered                     | —                                                                    |
| Queue waiting message      | When the user enters the queue                      | `{position}` queue position, `{wait_time}` estimated wait in minutes |
| Successful handoff message | After a support agent is assigned                   | `{agent_name}` support agent's name                                  |
| Queue full notification    | When the queue reaches its limit                    | —                                                                    |
| Timeout notification       | When a queue timeout returns the conversation to AI | —                                                                    |

The message shown when a support agent takes over but does not reply before the conversation times out and returns to AI is configured under Assignment Settings, not this subtab. See [Automatically Return to AI When an Agent Does Not Reply](#agent-reply-timeout).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-bfb296d7c058394b5742f475287a28dc58473989%2Fhandoff-transfer-messages.png?alt=media" alt="Handoff messages settings screen"><figcaption><p>Handoff messages: messages for each stage and available variables</p></figcaption></figure>

### System Status Banners Visitors See in Web Chat <a href="#visitor-status-banners" id="visitor-status-banners"></a>

The handoff messages in the table above are sent as Agent messages with content you customize. In addition, when a conversation's status changes, Web Chat inserts a **system status banner with small text on a gray background** between messages (preceded by a small colored dot). Its text is fixed and cannot be customized; both types of messages appear. The status banner text is as follows:

| Event                                          | Status Banner Text                                                                                                                                                                      |
| ---------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Human handoff triggered                        | Transferring you to a human support agent. Please wait...                                                                                                                               |
| Entering the queue                             | You are currently number N in the queue, with an estimated wait of M minutes                                                                                                            |
| Queue full                                     | Our support agents are busy. Please try again later or continue chatting with the AI assistant                                                                                          |
| Support agent assigned                         | Support agent {support agent name} is now assisting you                                                                                                                                 |
| Queue timeout returns conversation to AI       | Our support agents are currently busy. You have been returned to the AI assistant for continued assistance                                                                              |
| Agent reply timeout returns conversation to AI | Displays your configured “Return to AI message”; no status banner appears if the message is blank (see [Automatically Return to AI When an Agent Does Not Reply](#agent-reply-timeout)) |
| Support agent returns conversation to AI       | You have been returned to the AI assistant for continued assistance                                                                                                                     |
| Visitor cancels human handoff                  | At your request, the AI assistant will now assist you                                                                                                                                   |
| Conversation handed to AI                      | The AI assistant will now assist you                                                                                                                                                    |
| Outside service hours                          | Currently outside service hours                                                                                                                                                         |
| Other status changes                           | Conversation status updated                                                                                                                                                             |

Other conversation platforms (LINE, Teams, and others) do not display this status banner. Visitors receive only your custom handoff messages, so we recommend filling in the queue waiting and successful handoff messages.

### While Queuing <a href="#queue-period" id="queue-period"></a>

By default, users who send another message while waiting for human support receive no response, which can make them feel ignored. The <mark style="color:blue;">While Queuing</mark> section at the bottom of the <mark style="color:blue;">Handoff Messages</mark> subtab provides two switches (both off by default) that you can enable separately:

* <mark style="color:blue;">Repeat Queue Reminder</mark>: When a user in the queue sends another message, the system replies with a waiting reminder to confirm that they are still in the queue
* <mark style="color:blue;">Allow Users to Cancel Human Handoff</mark>: Users in the queue can click the <mark style="color:blue;">Let AI Answer</mark> button or enter a cancellation keyword to return to AI assistance themselves instead of continuing to wait

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b5bfac3e4701d135bc10834191bd28cd8a48dbfa%2Fhandoff-queue-period.png?alt=media" alt="While Queuing section in the Handoff Messages subtab"><figcaption><p>The While Queuing section at the bottom of the Handoff Messages subtab: both switches are off by default</p></figcaption></figure>

The following scenario illustrates the combined effect of these settings:

> A support supervisor notices that users often wait too long during the evening peak and repeatedly ask “Is anyone there?” She enables both switches under While Queuing for the Web platform, keeps the default text, and saves. When a queued user sends another message, they receive “Transferring you to a human support agent. Please wait” with a “Let AI Answer” button. A user who only wants to check business hours clicks the button and immediately receives “AI will now assist you.” AI then answers the question they asked while queuing, without making them wait for a support agent.

#### Repeat Queue Reminder <a href="#queue-reminder" id="queue-reminder"></a>

After enabling this option, you can configure:

| Setting               | Description                                                                                                                                                                                                                                                 |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Waiting reminder text | The reply sent when a queued user sends another message. Enabling the switch automatically fills in the default text “Transferring you to a human support agent. Please wait”                                                                               |
| Reminder cooldown     | The minimum interval between two waiting reminders in the same conversation (10–3600 seconds; default 60 seconds). The initial queue waiting message also starts the cooldown, preventing repeated reminders when a user sends messages in rapid succession |

The waiting reminder is fixed text sent directly by the system, without AI generation.

{% hint style="info" %}
If Allow Users to Cancel Human Handoff is also enabled, the system automatically appends cancellation instructions to each waiting reminder. You do not need to include them in the reminder text (they are not appended to the first queue waiting message sent on entering the queue). Web Chat and LINE display a cancel button below the reminder; other platforms append a line of instructions (for example, enter “Let AI Answer” to receive assistance from the Agent instead).
{% endhint %}

#### Allow Users to Cancel Human Handoff <a href="#queue-cancel" id="queue-cancel"></a>

The cancel button and text instructions are only appended to waiting reminders sent by Repeat Queue Reminder. We recommend enabling both switches so users can see how to cancel.

After enabling this option, you can configure:

| Setting               | Description                                                                                                                                                                                                                                                                  |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Cancel button text    | The text on the quick reply button below the waiting reminder. Defaults to “Let AI Answer,” with a limit of 20 characters. Clicking the button sends this text as a message                                                                                                  |
| Cancellation keywords | Cancellation occurs only when the user's message, after trimming leading and trailing whitespace, **exactly matches** a keyword; fuzzy matching is not used. Defaults to “Let AI Answer,” “I won't wait,” and “AI is fine.” Requires 1–10 keywords, each up to 20 characters |
| Return message        | The system reply after the user cancels. Defaults to “AI will now assist you”                                                                                                                                                                                                |

After the user cancels:

1. The conversation leaves the queue, returns to AI replies, and sends the return message
2. AI then answers the last message the user sent while queuing, so the user does not need to repeat the question. The message that triggered human handoff is excluded. If the user sent no messages while queuing, AI waits for their next message before replying

{% hint style="warning" %}
Cancellation works only while the conversation is still queued and has not been assigned to a support agent. Automatic assignment counts as assignment even if the agent has not replied yet. Once assigned, any cancellation keyword the user enters is treated as a normal message and passed to the support agent. No separate notification is sent to support agents when a user cancels.
{% endhint %}

Saved settings take effect immediately and apply to the next message sent while queuing. Turning off <mark style="color:blue;">Enable Human Handoff</mark> also hides this section.

## Service Hours <a href="#service-hours" id="service-hours"></a>

After you turn on <mark style="color:blue;">Enable Service Hours</mark>, human handoff operates only during the configured hours. You can set the <mark style="color:blue;">Time Zone</mark> and start and end times for each day of the week, or quickly apply <mark style="color:blue;">Monday–Friday 09:00–18:00</mark>.

If a handoff is triggered outside service hours, <mark style="color:blue;">Offline Behavior</mark> determines what happens:

* **Display an offline message**: Do not transfer the conversation; send the offline message and end the current reply. AI still answers subsequent general questions
* **Accept messages**: Display the offline message and place the conversation in the Unassigned queue for a support agent to take over during service hours

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-797fb69be8d3c084b426603c9b179399f5413cf9%2Fhandoff-service-hours.png?alt=media" alt="Service hours settings screen"><figcaption><p>Service hours: weekly schedule and offline behavior</p></figcaption></figure>

## Assignment Settings <a href="#dispatch-settings" id="dispatch-settings"></a>

### Assignment Mode <a href="#dispatch-mode" id="dispatch-mode"></a>

Use <mark style="color:blue;">Assignment Mode</mark> to choose how conversations requiring human support reach a support agent:

* **Automatic assignment** (default): The system automatically assigns human handoff conversations to available support agents according to the routing model
* **Claim mode**: The system does not assign automatically. Conversations remain in the Unassigned list until an online support agent clicks <mark style="color:blue;">I'll Take Over</mark> to claim one

In claim mode, <mark style="color:blue;">Routing Model</mark>, <mark style="color:blue;">Tag Routing</mark>, and <mark style="color:blue;">Reassign on Timeout</mark> are hidden and unused. You can still assign or reassign manually from the conversation page: use <mark style="color:blue;">Assign Agent</mark> for an unassigned conversation and <mark style="color:blue;">Transfer</mark> for one that already has an owner. In claim mode, you can also select <mark style="color:blue;">No Timeout</mark> to keep conversations waiting until a support agent takes over, rather than returning them to AI after a queue timeout (see [Capacity and Timeout Settings](#capacity-and-queue)).

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-b25b38fbffbd5c4f1079fd1310e77f69239510a4%2Fhandoff-dispatch-claim-mode.png?alt=media" alt="Assignment mode screen with claim mode selected"><figcaption><p>Assignment mode: selecting claim mode displays a notice that routing model, tag routing, and timeout reassignment are unused</p></figcaption></figure>

### Select Support Agents <a href="#assignable-members" id="assignable-members"></a>

Under <mark style="color:blue;">Assignable Support Agents</mark>, select the agents for this platform. Automatic assignment only assigns conversations to agents who meet **all** of the following conditions:

1. Are on the assignable list
2. Have an enabled account and support permissions for this conversation platform
3. Have an availability status of Available and are not currently on scheduled leave (see [Agent Availability](#agent-availability))
4. Have fewer active conversations than the Maximum Concurrent Conversations per Agent limit

Each agent's current status (Paused or On Leave) appears next to their name and can be adjusted directly. See [Agent Availability](#agent-availability) for details.

### Routing Model <a href="#routing-model" id="routing-model"></a>

Only displayed when Assignment Mode is Automatic Assignment.

* **Round Robin**: Distributes conversations evenly among support agents in rotation
* **Least Active**: Prioritizes agents who are currently handling the fewest conversations

### Capacity and Timeout Settings <a href="#capacity-and-queue" id="capacity-and-queue"></a>

| Setting                                                 | Description                                                                                                                                                                                                                                                                                                                |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Maximum concurrent conversations per agent              | The maximum number of conversations one agent can handle at once. Agents at the limit receive no further assignments                                                                                                                                                                                                       |
| Queue timeout                                           | If no support agent takes over within this time (1–3600 seconds), the conversation automatically returns to AI replies and a timeout notification is sent. In claim mode, selecting No Timeout keeps the conversation waiting until an agent takes over                                                                    |
| Reassign on timeout                                     | Automatic assignment mode only. When enabled, a timeout assigns the conversation to the next available agent instead of returning it directly to AI. See below                                                                                                                                                             |
| Automatically return to AI when an agent does not reply | Available in both automatic assignment and claim modes; off by default. After an agent takes over, if no agent replies to the customer's message within the specified number of seconds, the conversation automatically returns to AI. See [Automatically Return to AI When an Agent Does Not Reply](#agent-reply-timeout) |
| Queue limit                                             | The maximum number of queued conversations. New handoff requests are skipped when the queue is full                                                                                                                                                                                                                        |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e3188794a19f2825351be430f7cf06b8444fae58%2Fhandoff-dispatch-routing.png?alt=media" alt="Assignment settings screen"><figcaption><p>Assignment settings: routing model, tag routing, and capacity and timeout settings</p></figcaption></figure>

{% hint style="info" %}
With No Timeout selected, there is no estimated wait, so `{wait_time}` in the queue waiting message is blank. We recommend not using it. When switching from claim mode back to automatic assignment, a previous No Timeout setting is replaced with the default queue timeout of 300 seconds.
{% endhint %}

### Reassign on Timeout <a href="#reassign-on-timeout" id="reassign-on-timeout"></a>

When you enable <mark style="color:blue;">Reassign on Timeout</mark> (off by default; automatic assignment mode only), both of the following situations cause the conversation to be reassigned to the next available agent. Agents who have already been assigned are skipped:

* **Queue timeout**: No one takes over before the queue timeout expires
* **Assigned but no reply**: The agent assigned automatically by the system does not reply to the user before the queue timeout expires

If no other available agents remain who have not already been assigned, the conversation returns to AI and a timeout notification is sent. Conversations assigned manually, transferred, or claimed by an agent are not automatically reassigned.

{% hint style="info" %}
To leave conversations in the Unassigned list for agents to claim, set <mark style="color:blue;">Assignment Mode</mark> to <mark style="color:blue;">Claim Mode</mark> instead of clearing the Assignable Support Agents list.
{% endhint %}

### Automatically Return to AI When an Agent Does Not Reply <a href="#agent-reply-timeout" id="agent-reply-timeout"></a>

Queue Timeout only applies to conversations **still in the queue, before an agent takes over**. Once an agent takes over, that limit no longer applies. If the agent then steps away or finishes their shift without replying, the customer remains in human support indefinitely. Enabling <mark style="color:blue;">Automatically Return to AI When an Agent Does Not Reply</mark> returns the conversation to AI if no support agent replies to the customer's message within the specified number of seconds. AI continues answering so the customer is not left waiting.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-47dd28a642cc05d2feeeb61047a635156e9a22c2%2Fhandoff-agent-reply-timeout-settings.png?alt=media" alt="Capacity and Timeout Settings panel: the automatic return to AI switch is below Queue Timeout; when enabled, it displays a reply timeout of 300 seconds and a return to AI message"><figcaption><p>Automatically Return to AI When an Agent Does Not Reply in Capacity and Timeout Settings: enabling it reveals the timeout and message fields</p></figcaption></figure>

This setting is under <mark style="color:blue;">Capacity and Timeout Settings</mark> in the <mark style="color:blue;">Assignment Settings</mark> subtab and appears in both automatic assignment and claim modes:

| Setting                                                 | Description                                                                                                                                                                                                                                                                            |
| ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Automatically return to AI when an agent does not reply | Switch; off by default. When off, the two fields below are hidden                                                                                                                                                                                                                      |
| Reply timeout in seconds                                | 60–86400 seconds (up to 24 hours); default 300 seconds. Values outside this range turn the field red and prevent you from clicking <mark style="color:blue;">Save</mark> successfully                                                                                                  |
| Return to AI message                                    | The message sent to the customer when the conversation returns to AI. Enabling the switch automatically fills in “Our support agents are temporarily unable to reply. The AI assistant will continue assisting you.” Leave it blank to send no notification and have AI reply directly |

#### When the Timer Starts <a href="#agent-reply-timeout-timer" id="agent-reply-timeout-timer"></a>

* **From the customer's first unanswered message**: After an agent takes over, timing starts with the customer's first message that no one has answered. Multiple consecutive customer messages do not restart the timer
* **Unanswered messages already exist when the agent takes over**: For example, if the customer explained their request while queuing, timing starts as soon as the agent takes over (through automatic assignment, manual assignment, or clicking I'll Take Over)
* **Any support agent's reply stops the timer**: A reply sent to the customer by any agent, not just the assigned agent, stops the timer. Timing starts again with the customer's next message. Copilot drafts and system messages such as handoff notifications and queue reminders do not count as replies
* **Transfer to another support agent**: If unanswered messages remain, the new agent gets the full configured timeout starting when they take over
* **Voice conversations are not timed**: Only text messages count

When the timer expires, the system checks again that the conversation is still handled by human support, the switch is still enabled, and no agent has replied. Only then does it return the conversation to AI. No action is taken if the conversation has meanwhile returned to AI, been resolved, or returned to the queue, or an administrator has disabled the switch. Changing the timeout affects only timers started afterward.

#### After Returning to AI <a href="#agent-reply-timeout-result" id="agent-reply-timeout-result"></a>

1. The assignment is removed and automatic AI replies resume. The conversation page status becomes “AI Agent Handling”
2. If a notification message is configured, it is sent to the customer: Web Chat displays it as a gray system status banner, while other platforms such as LINE send it as a normal message from the AI assistant
3. AI replies once to the customer's **last** unanswered message. Earlier unanswered messages and exchanges during human support remain in the conversation history, so AI also considers that context
4. The <mark style="color:blue;">Conversation Timeline</mark> in the conversation details records “Returned to AI after agent reply timeout,” with the description “{support agent name} did not reply within N seconds. Automatically returned to AI Agent”

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-eeb432a02486737f7ca0c8e5ff558aafad7537ed%2Fhandoff-agent-reply-timeout-timeline.png?alt=media" alt="Conversation page: a return to AI message and AI reply appear below the customer&#x27;s question; the status shows AI Agent Handling; the top entry in the Conversation Timeline on the right records a return to AI after the agent failed to reply within 60 seconds"><figcaption><p>After timeout: the notification and AI reply follow the customer's question, and the Conversation Timeline records the return to AI after an agent reply timeout</p></figcaption></figure>

If the notification does not reach the customer, the timeline description adds “(notification not delivered).” If AI fails to continue replying (for example, because the conversation platform quota is exhausted), the conversation still returns to AI. The customer sees the existing AI error message, and the timeline adds “(AI reply failed: reason).”

The following scenario illustrates this setting:

> A support supervisor at an online store notices that evening agents often take over conversations just before finishing their shifts and forget to reply, leaving customers to discover the next day that no one responded. She enables Automatically Return to AI When an Agent Does Not Reply on the Web conversation platform, sets the timeout to 300 seconds, keeps the default notification, and saves. Later, an agent takes over a customer asking about shipment progress but steps away without replying. Five minutes later, the customer sees “Our support agents are temporarily unable to reply. The AI assistant will continue assisting you.” AI then answers the shipment question. The next day, the supervisor sees “○○ did not reply within 300 seconds. Automatically returned to AI Agent” in the Conversation Timeline and can identify the conversation and the agent who did not respond.

#### How This Differs from Other Timeout Settings <a href="#agent-reply-timeout-comparison" id="agent-reply-timeout-comparison"></a>

| Setting                                                 | Conversations It Applies To                                                          | When Time Expires                                                                           |
| ------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------- |
| Queue timeout                                           | Queued conversations that no agent has taken over                                    | Return to AI and send a timeout notification                                                |
| Reassign on timeout                                     | Automatically assigned conversations where the assigned agent has not yet replied    | Reassign to the next available agent; return to AI only after all agents have been tried    |
| Automatically return to AI when an agent does not reply | Conversations with an assigned agent where the customer's message remains unanswered | Return to AI, send the return to AI message, and have AI answer the last unanswered message |

When both options are enabled, automatically assigned conversations where the agent has not yet replied are handled by Reassign on Timeout first. Once an agent has replied, or if the conversation was manually assigned, transferred, or claimed by an agent, the agent reply timeout applies instead. No Timeout in claim mode only affects queuing; this setting still applies once an agent takes over.

{% hint style="info" %}
When a support agent turns automatic AI replies back on in a conversation, AI handles replies and no timer runs. If the customer asks for a human again after returning to AI, the standard handoff process starts again.
{% endhint %}

### Tag Routing <a href="#tag-routing" id="tag-routing"></a>

After you turn on <mark style="color:blue;">“Enable tag routing”</mark>, the system assigns conversations to members associated with their conversation tags (for example, conversations tagged “Billing” go to members of the billing team). Before using this feature, create conversation tags and assign tags to members. We also recommend enabling “Conversation analysis” so that conversations are tagged automatically during handoff. If a tag has no associated members, the system falls back to the standard assignment logic.

### Reassign returning customers to the previous assignee <a href="#return-to-previous-assignee" id="return-to-previous-assignee"></a>

By default, when a customer sends another message after a conversation is marked “Resolved”, the conversation reopens and AI resumes replying. The agent who handled it is not notified that the customer has returned. With <mark style="color:blue;">“Reassign returning customers to the previous assignee”</mark> enabled, customers who return within the configured number of hours are sent directly back to their previous agent, without having to queue again or repeat their issue to someone else.

This setting is on the <mark style="color:blue;">“Assignment settings”</mark> subtab, above <mark style="color:blue;">“Capacity and timeout settings”</mark>. It appears in both automatic assignment and manual pickup modes:

| Setting                                               | Description                                                                                                                                                                                                                                                                 |
| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reassign returning customers to the previous assignee | A toggle, off by default. When off, the return window field below is hidden, and resolved conversations return to AI as usual                                                                                                                                               |
| Return window                                         | 1–720 hours (up to 30 days), with a default of 24 hours, measured from when the conversation was marked resolved. Values outside this range turn the field red and display “Enter 1–720 hours (up to 30 days)”. Clicking <mark style="color:blue;">“Save”</mark> is blocked |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-cdcc8486bf6c133078d47432a4ba327baf5c9368%2Fhandoff-return-to-owner-settings.png?alt=media" alt="The reassign returning customers to the previous assignee section in Assignment settings: the toggle is on, the return window below is set to 24 hours, and the description states that the window starts when the conversation is marked resolved"><figcaption><p>Enabling “Reassign returning customers to the previous assignee” displays the “Return window” field below</p></figcaption></figure>

#### How returning customers are handled <a href="#return-to-previous-assignee-flow" id="return-to-previous-assignee-flow"></a>

A customer is considered to be returning only when all of the following conditions are met:

* The conversation was marked resolved while assigned to and being handled by a human agent (if the agent clicked <mark style="color:blue;">“Transfer back to AI Agent”</mark> before resolving it, AI still replies when the customer returns)
* The customer sends a text message within the return window (messages during voice calls do not count)
* The conversation channel is currently within its [service hours](#service-hours)

For a returning customer, the outcome depends on the previous agent’s current status:

| Previous agent                                                                                                                                                                                                                                           | Outcome                                                                                                                                                                                                                                                                                                                                                                                              |
| -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Available to take over: their account is still in the organization, they still have access to this conversation channel, their availability is “Available”, they are not on scheduled time off, and they are currently online (with the admin page open) | The conversation reopens and is assigned directly to the previous agent. AI does not reply to this message. The customer receives the “Successful handoff prompt”, and the agent receives the usual assignment notification. The “Assignable agents” list and the maximum number of concurrent conversations are not checked here                                                                    |
| Offline, not accepting conversations, on scheduled time off, no longer in the organization, or no longer authorized to access this conversation channel                                                                                                  | Standard human assignment applies instead: the customer receives the “Handoff notification message”, and the conversation enters the queue. Automatic assignment routes it to an available agent other than the previous agent; if nobody can take it, the queue timeout setting applies. In manual pickup mode, it stays “Unassigned” until an agent picks it up. AI does not reply to this message |

AI still takes over and replies as it would with this setting off if the return window has expired, the channel is outside service hours, the queue is full, or the assignment process fails.

When the conversation is reassigned to the previous agent, a system message appears in the conversation. The same description is recorded in <mark style="color:blue;">“Conversation timeline”</mark> in the conversation details: “The customer sent another message within N hours of resolution. Automatically reassigned to the previous assignee {agent name}.” If standard human assignment applies instead, the timeline records the usual “Handoff triggered” event.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9caa0748580775f93cf80857cf23dbff0d3b9a56%2Fhandoff-return-to-owner-conversation.png?alt=media" alt="Conversation page: after the agent replies, the status changes from In progress to Resolved. When the customer sends another message, it returns to In progress. A system message below says that the customer messaged again within 24 hours of resolution and was automatically reassigned to the previous assignee. The bottom indicates that this agent is currently handling the conversation"><figcaption><p>When a customer returns within the window, the conversation is automatically reassigned to the previous agent</p></figcaption></figure>

The following scenario illustrates this setting:

> A support manager at a software company notices that customers often return the day after an issue is resolved with follow-up questions, only to be handled by AI and have to explain everything again. In “Assignment settings” for the company website’s support channel, she enables “Reassign returning customers to the previous assignee”, leaves the return window at 24 hours, and saves. Later, a customer requests human assistance to check an invoice. An agent takes over, replies, and clicks “Resolve”. A few minutes later, the customer sends, “The invoice should be made out to our company. Could you reissue it?” The conversation goes directly back to the same agent. The customer sees “A support agent has taken over your conversation”, and AI does not interrupt. On another occasion, the customer returns while that agent is not accepting conversations, so the conversation enters the queue for another agent to pick up.

{% hint style="info" %}
Reassignment to the previous agent counts as automatic assignment by the system. If [reassign on timeout](#reassign-on-timeout) or [automatically transfer back to AI when a human agent does not reply in time](#agent-reply-timeout) is enabled, it also applies to this conversation. If the previous agent later stops accepting conversations, the conversation is reassigned according to the [agent availability](#agent-availability) rules.
{% endhint %}

### Agent availability <a href="#agent-availability" id="agent-availability"></a>

Agents can indicate whether they can currently accept new conversations, so automatic assignment routes conversations only to those who can handle them. Availability has two layers. Either condition below excludes an agent from automatic assignment:

* **Availability status**: “Available” or “Not accepting conversations”. Automatic assignment skips agents who are not accepting conversations and resumes immediately when they switch back to available. When an agent stops accepting conversations, conversations automatically assigned to them that they have not yet replied to are reassigned to the next available agent (if nobody can take them, they return to the unassigned queue, and this is recorded in the conversation timeline). Conversations they have already replied to, manually assigned or transferred conversations, and conversations they picked up themselves are left as they are
* **Scheduled time off**: Set one or more periods of leave or off-duty time in advance, down to the minute, with no overlaps. The agent receives no automatic assignments during these periods and becomes available again automatically when they end

Agents can change their own status and configure “My time off” on the conversation page. See [Set your own availability status](https://docs.maiagent.ai/maiagent-user-guide/en/serve/daily-operations/human-handoff-operations.md#my-availability) for instructions. Channel administrators can also change an agent’s <mark style="color:blue;">“Status”</mark> directly in the <mark style="color:blue;">“Assignable agents”</mark> list or click <mark style="color:blue;">“Time off”</mark> to schedule their time off. To change another agent’s status or time off, you must be the organization owner or have edit permission for at least one conversation channel whose assignment list includes that agent.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-eb41d7c72e028ef8df4dd201b39dd8b3a4a72382%2Fhandoff-dispatch-mode-member-status.png?alt=media" alt="Assignable agents list and status dropdown"><figcaption><p>Assignable agents: change each agent’s “Status” directly or click “Time off”</p></figcaption></figure>

The following scenario illustrates scheduled time off:

> A support manager learns that an agent will take next Wednesday off. She finds the colleague in the agent list under “Assignment settings”, clicks “Time off”, adds a period covering all of Wednesday, and saves. On Wednesday, incoming conversations that require human support are no longer assigned to that agent. Once the time off ends, the agent automatically returns to the assignment pool, without anyone having to remember to switch them back.

{% hint style="info" %}
Scheduled time off and the channel’s [service hours](#service-hours) both apply. When an administrator schedules time off in “Assignment settings”, times are displayed in the service hours time zone. Time off only affects automatic assignment of new conversations. Stopping acceptance of conversations also skips new assignments, but additionally reassigns automatically assigned conversations the agent has not yet replied to. Neither affects conversations the agent has already replied to. Manual assignment, transfers, and agents picking up conversations from “Unassigned” remain available as usual.
{% endhint %}

### Agent workload <a href="#agent-workload" id="agent-workload"></a>

The <mark style="color:blue;">“Agent workload”</mark> panel at the bottom of the page shows each agent’s in-progress and resolved conversation counts, status, and whether they are <mark style="color:blue;">“Online”</mark> (currently have the admin page open), along with the current number of queued conversations. This gives administrators a real-time view of the workload. Statuses are displayed in this order of priority: On scheduled time off > Not accepting conversations > At capacity > Available for assignment.

## Notifications <a href="#notifications" id="notifications"></a>

When a conversation is assigned to an agent, the system alerts the assignee and CC recipients (such as a supervisor) through <mark style="color:blue;">“Notification center announcements”</mark> and <mark style="color:blue;">“Email notifications”</mark>. Notification templates are customizable. For complete setup instructions, template variables, and frequently asked questions, see [Human handoff notifications](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/human-handoff/handoff-notification.md).

{% hint style="warning" %}
Notifications are sent when a conversation is assigned to an agent. In message mode or manual pickup mode (when conversations remain in the “Unassigned” queue), no Email notification is sent at this stage. Arrange for agents to check the “Unassigned” list regularly.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/human-handoff.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
