Human Agent Handoff Notifications

Notify internal staff through the notification center and Email when conversations are assigned to human agents; notify external systems through Webhook when handoff is triggered, assigned, returned t

When a conversation moves from AI to a human and is assigned to a support agent, MaiAgent can send notifications through Email, the Notification Center, and Webhook Notifications (System Integration). The first two channels notify agents and supervisors. Webhook allows external systems such as dispatch, alerting, or CRM systems to continue processing. It also sends events when AI determines that a human handoff is needed, when a conversation returns to AI, and when the queue times out, allowing external systems with their own human support agents to take over the full workflow.

This feature is part of Human Handoff Settings. Notifications are sent only after Enable Human Handoff is turned on for the conversation platform.

When Are Notifications Sent?

Notifications include three channels that can be enabled or disabled independently. Email and the Notification Center send notifications when a conversation is assigned to an agent (Human Assigned). Webhook covers the following four events in the human handoff lifecycle:

• Email Notifications: Sent to the assigned agent. Copy recipients (such as supervisors) also receive a copy of the same email, with all recipients visible to one another.

• Notification Center Announcements: A “Human Handoff Notification” announcement is sent to the assigned agent and copy recipients through the bell icon (Notification Center) at the top right of the admin interface. It includes a link to the conversation.

• Webhook Notifications (System Integration): Sends JSON events from the human handoff lifecycle to the HTTPS URL configured by an administrator so external systems can automatically create tickets, take over, or issue alerts: handoff.requested when AI determines that a human handoff is needed; handoff.assigned when the conversation is assigned to an agent; handoff.returned_to_ai when an agent clicks Return to AI Agent to hand the conversation back to AI; and handoff.queue_timeout when a queue timeout automatically returns the conversation to AI. These four events correspond to “Handoff Triggered,” “Human Agent Took Over,” “Return to AI Agent,” and “Queue Timeout” on the conversation timeline.

Email and the Notification Center send notifications only when a conversation is assigned. If a conversation has entered the human handoff queue but has not yet been assigned to a specific agent, these two channels do not send notifications. An enabled Webhook still sends handoff.requested when AI determines that a human handoff is needed.

What Notifications Do Not Do

• Clicking a link in an email or announcement only opens the conversation. It does not automatically switch the conversation to human response mode. After opening the conversation, the agent must still click I'll Take Over above the conversation to stop automatic AI replies and take over.

• Notifications are not sent to customers. They are reminders for internal staff only and do not affect the human handoff messages customers see.

• Webhook sends only the identifying information required for the event and the link to the conversation in the admin interface. It does not include conversation text or provide dedicated adapters for specific third-party systems.

Use Case

A support supervisor wants every human handoff to enter the company's dispatch system automatically, without relying on staff to monitor announcements or emails. She opens Human Handoff Settings for the conversation platform, enables Webhook Notifications (System Integration) on the Notifications tab, enters the dispatch system's HTTPS receiver URL, and saves. The next time a conversation is assigned to an agent, the dispatch system immediately receives a handoff.assigned event and automatically creates a ticket. When the agent finishes and clicks “Return to AI Agent,” the dispatch system receives handoff.returned_to_ai and automatically closes the ticket. The supervisor does not need to manually relay any information throughout this process.

How to Configure Notifications

1

Open Notification Settings

1. Go to Customer Conversations → Conversation Platforms, then click Edit for the platform you want to configure.

2. Under “Advanced Features” in the settings menu on the left, click Human Handoff Settings. First confirm that Enable Human Handoff at the top is turned on.

3. Click the Notifications subtab.

If human handoff is not enabled, Human Handoff Settings in the left menu shows “Not Configured.” The page displays only the Enable Human Handoff switch, and subtabs such as Notifications do not appear. Enable human handoff and save before proceeding with the settings below.

2

Choose Notification Channels

The Notifications tab provides three independent switches that you can enable or disable as needed:

• Notification Center Announcements: Sends an announcement to the assigned agent and copy recipients in the Notification Center when a conversation is assigned.

• Email Notifications: Emails the assigned agent and sends copies to the specified recipients when a conversation is assigned.

• Webhook Notifications (System Integration): Sends events to the specified external system when AI determines that a human handoff is needed, when a conversation is assigned, when it returns to AI, and when the queue times out. Disabled by default; enable it when you need an integration.

Disabling one channel does not stop other enabled channels from sending notifications.

Human Handoff Settings → Notifications subtab: three channel switches, copy recipients, and notification templates

3

Configure Webhook (Optional)

1. Enable Webhook Notifications (System Integration) to expand the Webhook fields below.

2. Enter the external system's receiver URL in Webhook URL. The URL must start with https://. Leaving it empty displays “A Webhook URL is required when Webhook is enabled”; entering http:// displays “The Webhook URL must use HTTPS.” You cannot save in either case.

3. If the receiver needs to verify the event source, enter a shared secret agreed upon by both parties in Signing Secret (Optional). When signing is enabled, every delivery includes the X-MaiAgent-Signature-256 header.

The “Webhook URL” and “Signing Secret (Optional)” fields expanded after enabling Webhook Notifications (System Integration)

Managing the Secret After Setup:

• After the secret is saved, it is not displayed again. The field instead shows “Configured—leave blank to keep unchanged.” To replace the secret, enter a new value and save. Leaving the field blank preserves the existing secret.

• To stop signing, click Clear Secret beside the field and confirm. Subsequent deliveries no longer include the signature header. If the receiver is verifying signatures, it will start rejecting deliveries, so adjust the receiver before clearing the secret.

For event fields, signature verification, and retry behavior, integration developers should refer to Human Handoff Webhook Events in the API documentation. If human agents will reply through your own support system, the “Let an External System Take Over Conversations After Human Handoff” section on the same page explains how to combine the conversation platform's Webhook (message delivery and reception) with the message API for two-way synchronization.

The receiver should ensure that only appropriate personnel can view identifying information and links to conversations in the admin interface included in events. Disable Webhook notifications if you no longer use this integration.

4

Configure Copy Recipients (Optional)

To keep supervisors or others informed about human handoffs, configure copy recipients:

• Send Notification Copies (Members): Select the members who should receive copies (such as supervisors).

• Send Notification Copies (Groups): Select the groups that should receive copies. Each group automatically expands to include all its members.

The assigned agent is automatically excluded from copy recipients to avoid receiving a duplicate copy.

5

Customize Notification Templates (Optional)

Four template fields let you customize notification text. Default templates are populated when human handoff is enabled:

• Announcement Title Template

• Announcement Body Template

• Email Subject Template

• Email Body Template

You can use the following variables in templates. They are automatically replaced with actual values from the conversation when a notification is sent:

Variable	Replacement Value
{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

Four template fields and hints for available variables

Default Template Reference

Email Subject Template

[Human Handoff] A conversation has been assigned to you — {inboxName}

Email Body Template

Hello {agentName},

A conversation from {customerName} in the support channel “{inboxName}” has been assigned to you.
Click the following link to open the conversation in the admin interface:
{conversationUrl}

Announcement Title Template

Conversation assigned: {customerName}

Announcement Body Template

A conversation from {customerName} in the support channel “{inboxName}” has been assigned to {agentName}. Please open the admin interface to check it.

6

Save Settings

Save when finished; the settings take effect immediately. The system then sends notifications according to each channel's switch and event scope: Email and the Notification Center send notifications only on assignment; Webhook sends events when AI determines that a human handoff is needed, on assignment, on return to AI, and on queue timeout.

Turning off Enable Human Handoff also stops notifications, but the notification settings are preserved. Enabling human handoff again restores the existing settings.

What Agents and Supervisors Receive

Email Notifications

The assigned agent receives a MaiAgent-branded email with a subject and body generated from the templates and a link to the conversation. Configured copy recipients receive the same email as CC recipients, with all recipients visible to one another.

Notification Center Announcements

Click the bell icon at the top right of the admin interface to open the Notification Center, then switch to the Organization Announcements tab to see announcements of type Human Handoff Notification. Click Go to Take Over in an announcement to open the conversation directly.

Human handoff notifications are frequent transactional events. To keep the announcement list from becoming overwhelmed, these announcements automatically expire 7 days after they are sent.

What External Systems Receive

External systems receive a JSON event containing only identifying information: the event name, event ID and occurrence time; IDs for the conversation, conversation platform, organization, customer, and 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 event types share the same fields. For events without an assigned agent (handoff requested, return to AI, and queue timeout), the assigned agent is empty. For detailed fields and verification examples, see Human Handoff Webhook Events in the API documentation.

Notes

• Permissions: Only users with permission to configure the conversation platform can view and edit notification settings. Existing human handoff settings permissions apply.

• Agent Has No Email Address: If the assigned agent has no email address configured, the system automatically skips the Email channel, but Notification Center announcements are still sent as usual. Other recipients are not affected.

• Independent Channels: Email, the Notification Center, and Webhook operate independently. A delivery failure in one channel does not affect other channels 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. Human handoff and other notification channels continue to operate during this time. Receivers should deduplicate events using the event ID.

• Different from the Conversation Platform's “Webhook”: The conversation platform has a separate Webhook feature that sends conversation messages themselves. The human handoff Webhook sends only handoff status events. Their settings and secrets are independent and do not affect each other.

• Taking Over Is Still Required After Opening a Conversation: As described above, links only open the conversation. To actually take over, click I'll Take Over above the conversation.