Skip to main content
A handoff transfers the conversation from the PolyAI agent to a human agent. This happens automatically when the PolyAI agent determines it cannot handle the user’s request. There are two handoff modes: server-managed (PolyAI handles routing internally) and client-managed (your app handles routing).

​
Server-managed handoff

In the typical flow, PolyAI manages the handoff internally:
During the handoff, the user continues to send EVENT_TYPE_USER_MESSAGE events — the messages are routed to the live agent instead of the PolyAI agent.

​
Client-managed handoff

In some configurations, the server cannot handle the handoff and asks your client to do it:
When you receive CLIENT_HANDOFF_REQUIRED, redirect the user to the appropriate support channel (e.g. open a Zendesk widget, redirect to a phone number). The reason and queue_name fields give context for routing.

​
Failed handoffs

See Server events → Handoff events for the full event payloads.

​
Conversation flow (full session)

Last modified on May 18, 2026