> 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/handoff-notification.md).

# Human Agent Handoff Notifications

When a conversation is assigned to a human support agent, notify internal staff through the Notification Center and Email, and notify external systems through Webhook when a handoff is triggered, assi

When a conversation is handed over from the AI to a human and **assigned to a support agent**, MaiAgent can send notifications through <mark style="color:blue;">Email</mark>, the <mark style="color:blue;">Notification Center</mark>, and <mark style="color:blue;">Webhook notifications (system integration)</mark>. The first two channels alert agents and supervisors; the Webhook lets external systems such as dispatch, alerting, or CRM systems take over from there. It also sends events when the AI decides to hand off to a human, when a conversation is returned to the AI, and when the queue times out, so an external system with its own human support team can take over completely.

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

{% hint style="info" %}
This feature is part of “**Human Support Handoff Settings**.” Notifications are sent only after <mark style="color:blue;">human support handoff is enabled</mark> on the conversation platform.
{% endhint %}

## When Are Notifications Sent? <a href="#when-notified" id="when-notified"></a>

Notifications have three channels that can each be turned on or off separately. **Email and the Notification Center** are sent when a conversation is assigned to an agent (Human Assigned). **Webhook** covers the following four human handoff lifecycle events:

* **Email notification**: Sent to the assigned agent. Carbon copy (CC) recipients, such as supervisors, also receive the same email (all recipients can see each other).
* **Notification Center announcement**: A “Human handoff notification” announcement is sent to the assigned person and the CC recipients through the bell icon (Notification Center) at the top right of the admin interface, with a link to the conversation.
* **Webhook notification (system integration)**: Sends JSON events for the human handoff lifecycle to an HTTPS URL set by the administrator, so external systems can automatically open tickets, take over conversations, or raise alerts: `handoff.requested` when the AI decides to hand off to a human, `handoff.assigned` when the conversation is assigned to an agent, `handoff.returned_to_ai` when an agent clicks <mark style="color:blue;">Return to AI Agent</mark> to hand the conversation back to the AI, and `handoff.queue_timeout` when the conversation is automatically returned to the AI after a queue timeout. The four events correspond to “Handoff triggered,” “Human agent took over,” “Returned to AI Agent,” and “Queue timeout” on the conversation timeline.

{% hint style="warning" %}
**Email and the Notification Center** send notifications only when a conversation is “**assigned**.” If a conversation has entered the human handoff queue but is **not yet assigned** to a specific agent, these two channels send nothing; an enabled **Webhook** still sends `handoff.requested` when the AI decides to hand off to a human.
{% endhint %}

### What Notifications Do Not Do <a href="#what-it-does-not-do" id="what-it-does-not-do"></a>

* Clicking the link in an Email or announcement only **opens the conversation**; it does **not** automatically switch the conversation to human response mode. After entering the conversation, the agent must still click the <mark style="color:blue;">Take Over</mark> button at the top of the conversation to stop the AI's automatic replies and take over as a human.
* Notifications are not sent to customers. They are purely **internal reminders for staff**, and the handoff message the customer sees is unaffected.
* The Webhook sends only the identifiers required by the event and a link to the conversation in the admin interface. It does not include conversation text, and it does not provide converters specific to any third-party system.

## Use Case <a href="#scenario" id="scenario"></a>

A support supervisor wants every human handoff to enter the company's dispatch system automatically, instead of relying on people watching announcements or Email. She opens the conversation platform's <mark style="color:blue;">Human Support Handoff Settings</mark>, turns on <mark style="color:blue;">Webhook notification (system integration)</mark> in the <mark style="color:blue;">Notifications</mark> tab, enters the HTTPS receiving URL of the company's dispatch system, and saves. The next time a conversation is assigned to an agent, the dispatch system immediately receives a `handoff.assigned` event and creates a ticket automatically. When the agent finishes and clicks “Return to AI Agent,” the dispatch system receives `handoff.returned_to_ai` and closes the ticket automatically. The supervisor never has to copy and paste any information by hand.

## How to Set Up Notifications <a href="#setup" id="setup"></a>

{% stepper %}
{% step %}

### Open Notification Settings <a href="#enter-settings" id="enter-settings"></a>

1. Go to <mark style="color:blue;">Customer Support Conversations</mark> → <mark style="color:blue;">Conversation Platforms</mark>, and click <mark style="color:blue;">Edit</mark> on the conversation platform you want to configure.
2. In the left settings menu under “Advanced Features,” click <mark style="color:blue;">Human Support Handoff Settings</mark>, and first confirm that <mark style="color:blue;">Enable Human Support Handoff</mark> at the top is turned on.
3. Click the <mark style="color:blue;">Notifications</mark> sub-tab.

{% hint style="info" %}
If human handoff is not yet enabled, <mark style="color:blue;">Human Support Handoff Settings</mark> in the left menu is labeled “Not configured,” and the page shows only the <mark style="color:blue;">Enable Human Support Handoff</mark> switch; sub-tabs such as <mark style="color:blue;">Notifications</mark> do not appear. Turn on human support handoff and save first, then continue with the settings below.
{% endhint %}
{% endstep %}

{% step %}

### Choose Notification Channels <a href="#channels" id="channels"></a>

The Notifications tab provides three independent switches that you can turn on or off as needed:

* <mark style="color:blue;">Notification Center announcement</mark>: When a conversation is assigned, sends an announcement through the Notification Center to the assigned person and the CC recipients.
* <mark style="color:blue;">Email notification</mark>: When a conversation is assigned, sends an Email to the assigned person and CC notifications to the specified recipients.
* <mark style="color:blue;">Webhook notification (system integration)</mark>: Sends events to the specified external system when the AI decides to hand off to a human, when a conversation is assigned, when it is returned to the AI, and when the queue times out. **Off by default**; turn it on when you need the integration.

If you turn off only one channel, the other enabled channels continue to send as usual.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-9bfb10b279b20accd92ea73ee04f8236a1948139%2Fhandoff-notification-channels.png?alt=media" alt="Notifications sub-tab of Human Support Handoff Settings"><figcaption><p>Human Support Handoff Settings → “Notifications” sub-tab: three channel switches, CC recipients, and notification templates</p></figcaption></figure>
{% endstep %}

{% step %}

### Set Up the Webhook (Optional) <a href="#webhook" id="webhook"></a>

1. Turn on <mark style="color:blue;">Webhook notification (system integration)</mark>. The Webhook fields expand below.
2. In <mark style="color:blue;">Webhook URL</mark>, enter the receiving URL of the external system. The URL must start with `https://`. If you leave it blank, the message “Webhook URL is required when Webhook is enabled” appears; if you enter `http://`, the message “Webhook URL must use HTTPS” appears. In both cases you cannot save.
3. If the receiver needs to verify the source of events, enter a mutually agreed secret in <mark style="color:blue;">Signing secret (optional)</mark>. Once signing is enabled, every delivery includes the `X-MaiAgent-Signature-256` header.

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-3badb22c7c48cd5e0a21af1a1acde0bae07922e0%2Fhandoff-notification-webhook.png?alt=media" alt="Webhook URL and signing secret fields after Webhook notification is turned on"><figcaption><p>The “Webhook URL” and “Signing secret (optional)” fields that expand after you turn on Webhook notification (system integration)</p></figcaption></figure>

**Managing the secret afterward**:

* After the secret is saved, it is **never shown again**, and the field changes to the prompt “Already set — leave blank to keep unchanged.” To change the secret, enter a new value and save; leave the field blank to keep the existing secret.
* To stop signing, click <mark style="color:blue;">Clear secret</mark> next to the field and confirm. After it is cleared, deliveries no longer include the signature header; if the receiver is verifying signatures, it will start rejecting events, so adjust the receiver before clearing.

{% hint style="info" %}
For the event field format, signature verification method, and retry behavior, integration engineers should refer to [Human handoff Webhook events](https://docs.maiagent.ai/api/preparation/handoff-webhook) in the API documentation. If human agents will take over replies in your own support system, the section “Handing the conversation to an external system after handoff” on the same page explains how to combine the conversation platform's <mark style="color:blue;">Webhook</mark> (message sending and receiving) with the message API to achieve two-way synchronization.
{% endhint %}

{% hint style="warning" %}
The receiver should make sure that only appropriate people can view the identifiers and the admin conversation link in the events. If you no longer use this integration, turn off Webhook notification.
{% endhint %}
{% endstep %}

{% step %}

### Set CC Recipients (Optional) <a href="#copy-recipients" id="copy-recipients"></a>

If you want supervisors or others to stay informed about human handoffs, set CC recipients:

* <mark style="color:blue;">Send CC notifications (members)</mark>: Select the members to receive CC notifications (for example, supervisors).
* <mark style="color:blue;">Send CC notifications (groups)</mark>: Select the groups to receive CC notifications; a group is automatically expanded to all of its members.

The assigned agent is automatically excluded from the CC recipients (so they do not receive a duplicate copy).
{% endstep %}

{% step %}

### Customize Notification Templates (Optional) <a href="#templates" id="templates"></a>

Four template fields let you customize the text of notifications. Default templates are filled in when you turn on human handoff:

* <mark style="color:blue;">Announcement title template</mark>
* <mark style="color:blue;">Announcement content template</mark>
* <mark style="color:blue;">Email subject template</mark>
* <mark style="color:blue;">Email body template</mark>

The following **variables** can be used in templates and are automatically replaced with the actual content of the conversation when sent:

| Variable            | Replaced with                                       |
| ------------------- | --------------------------------------------------- |
| `{agentName}`       | Name of the assigned support agent                  |
| `{inboxName}`       | Name of the conversation platform (support channel) |
| `{customerName}`    | Name of the customer (visitor)                      |
| `{conversationUrl}` | Link to the conversation                            |

<figure><img src="https://1360999650-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F6v6TNkkOQVfRYfcNirHL%2Fuploads%2Fgit-blob-e8a5d6b0e7eb74e9dfcd8ec9e386fd2fe9fbe5a8%2Fhandoff-notification-templates.png?alt=media" alt="Editing notification templates"><figcaption><p>The four template fields and the available variable hints</p></figcaption></figure>

<details>

<summary>Default template reference</summary>

**Email subject template**

```
【轉真人】對話已指派給您 — {inboxName}
```

**Email body template**

```
您好 {agentName}，

客服「{inboxName}」有一筆來自 {customerName} 的對話已指派給您。
請點擊以下連結進入後台對話：
{conversationUrl}
```

**Announcement title template**

```
對話已指派：{customerName}
```

**Announcement content template**

```
客服「{inboxName}」有一筆來自 {customerName} 的對話已指派給 {agentName}，請進入後台確認。
```

</details>
{% endstep %}

{% step %}

### Save Settings <a href="#save" id="save"></a>

Save when you are done, and the settings take effect immediately. After that, the system sends notifications according to each channel's switch and event scope: Email and the Notification Center send only on assignment, while Webhook sends when the AI decides to hand off to a human, on assignment, when returned to the AI, and when the queue times out.

{% hint style="info" %}
When you turn off <mark style="color:blue;">Enable Human Support Handoff</mark>, notifications stop being sent, but the notification settings are **kept**; turning human handoff back on restores the original settings.
{% endhint %}
{% endstep %}
{% endstepper %}

## What Agents and Supervisors Receive <a href="#what-recipients-see" id="what-recipients-see"></a>

### Email Notification <a href="#email" id="email"></a>

The assigned agent receives a MaiAgent-branded Email whose subject and body are generated from the templates and which contains a link to the conversation. The configured CC recipients receive the same email as **carbon copies** (all recipients can see each other).

### Notification Center Announcement <a href="#notification-center" id="notification-center"></a>

Click the bell at the top right of the admin interface to open the <mark style="color:blue;">Notification Center</mark>, then switch to the <mark style="color:blue;">Organization Announcements</mark> tab to see announcements of the type <mark style="color:blue;">Human handoff notification</mark>. Click <mark style="color:blue;">Go take over</mark> in the announcement to open the conversation directly. For full details on the Notification Center, see [Notification Center](https://docs.maiagent.ai/maiagent-user-guide/en/start/notifications.md).

{% hint style="info" %}
Human handoff notifications are high-frequency transactional events. To keep them from flooding the announcement list, these announcements **expire automatically 7 days** after they are sent.
{% endhint %}

### What the External System Receives <a href="#what-webhook-receives" id="what-webhook-receives"></a>

The external system receives a JSON event that contains only identifying information: the event name, event ID and time of occurrence, the conversation, the conversation platform, the organization, the customer, the ID of the agent assigned at the time of the event, and a link to the conversation in the admin interface. It contains no conversation text. All four events have the same fields; for events with no assigned agent (handoff triggered, returned to AI, queue timeout), the assigned agent is empty. For detailed fields and verification examples, see [Human handoff Webhook events](https://docs.maiagent.ai/api/preparation/handoff-webhook) in the API documentation.

## Notes <a href="#notes" id="notes"></a>

* **Permissions**: Only people with permission to configure the conversation platform can view and edit notification settings; the existing human handoff settings permissions apply.
* **Agent has no Email**: If the assigned agent has no Email set, the system automatically skips the Email channel, but **the Notification Center announcement is still sent as usual** and other recipients are unaffected.
* **Channels are independent**: Email, the Notification Center, and Webhook each operate on their own. A failure in one does not affect the others or the conversation assignment process.
* **Webhook failure handling**: If the external endpoint times out or returns an error, the system automatically retries three times in the background; during this time, human handoff and the other notification channels continue to work as usual. The receiver should use the event ID to remove duplicate events.
* **Different from the conversation platform's “Webhook”**: The conversation platform has a separate [Webhook](https://docs.maiagent.ai/maiagent-user-guide/en/build/conversation-settings/webhook.md) feature that delivers the conversation messages themselves; the human handoff Webhook sends only human handoff status events. The two have independent settings and secrets and do not affect each other.
* **Agents still need to take over after entering the conversation**: As noted above, the link only opens the conversation itself; actually taking over still relies on the <mark style="color:blue;">Take Over</mark> button at the top of the conversation.


---

# 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/handoff-notification.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.
