When handoff.enabled is true, the model may call escalate_to_human({ reason, summary }). Users can also escalate from the UI or agents can take over from the dashboard.
Conversation statuses
ai— model handles new user messages.waiting_human— queued for an agent; user messages are not sent to the model.human— agent is actively replying.resolved— closed; may be rated or converted to knowledge.
Realtime
End users connect with GET /api/v1/conversations/:id/ws?token=<sessionToken> (ConversationRoom Durable Object). Agents use GET /api/admin/inbox/ws (TenantInbox). Events include message.created, typing, conversation.updated, action.updated.
Webhooks
Optional handoff.webhookUrl receives JSON POSTs on escalation with the same X-Supportal-Signature scheme as connector calls. Use it to page on-call staff or open tickets in your system.
handoff.notifyEmail is supported as a stub/log in development; wire your own notification via webhook in production.
Returning to AI
Agents can set status back to ai or resolved from the dashboard. Resolved conversations can feed the knowledge pipeline.