Human handover notifications: where the pings go

Whenever the agent pauses a conversation, calls transfer_to_human,
or errors out, we fire a notification. This article covers where those
pings go and how to wire them up.

Four notification channels

Configure under Settings → Integrations → Notifications:

• Slack — OAuth install, channel picker, posts rich messages
• Discord — paste a webhook URL (Server → Integrations →
• Email — any inbox, one or many. Best for long-tail events you
• SMS — a phone number that gets texted for urgent events.

You can wire up any combination. Most operators use Slack + email
for routine, SMS for severe only.

The events

• needs_attention — a conversation paused itself. Fires for:
• human_handover — the agent called transfer_to_human.
• agent_error — a turn errored out. Includes the error
• approval_pending — an outbound reply was held by the

Each event has a severity: info, warning, error. Wire
integrations to route severity accordingly (errors to an on-call
Slack channel, info to an email digest).

Per-event subscribe

Each integration has per-event toggles so you can wire Slack for
needs_attention only, email for agent_error only, SMS just
for approval_pending. Default is "all events to all channels",
which is noisy — narrow it down after the first week.

What's in the payload

All notifications include:

• Agent name
• Contact ID (last 6 chars shown, full in the link)
• Reason / body (truncated to ~200 chars)
• Deep link to the conversation in the Inbox
• Timestamp + severity

Testing

Each integration has a Send test button on its config row. Fires
a real notification with dummy data so you can verify formatting
without waiting for an agent to pause.

When notifications feel spammy

Two patterns:

• Narrow subscriptions. Don't send every event to every channel.
• Tune stop conditions. If the same stop condition fires 50 times

Privacy note

Notifications include contact IDs + short message snippets. If you're
in a regulated industry (HIPAA, PCI), prefer email+SMS to a dedicated
admin inbox over Slack/Discord — the latter are easier to accidentally
over-share.