Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.poly.ai/llms.txt

Use this file to discover all available pages before exploring further.

This page lists every event in order for a complete session — what your client sends and what it receives.

​
Connection and agent join

StepDirectionEventWhat to do
1← ServerEVENT_TYPE_EVENT_BATCHHistory replay. Flatten the events array. Contains at least SESSION_START.
2↳ EVENT_TYPE_SESSION_STARTRead capabilities (streaming, heartbeat interval).
3Client →EVENT_TYPE_REQUEST_POLY_AGENT_JOINSend to start the conversation. New sessions only — skip on reconnect if agent already joined.
4← ServerEVENT_TYPE_REQUEST_POLY_AGENT_JOINEcho of your join request.
5← ServerEVENT_TYPE_POLY_AGENT_JOINEDAgent has joined. Read agent_name and agent_avatar_url for your UI.
6← ServerEVENT_TYPE_POLY_AGENT_THINKINGShow a typing indicator.
7← ServerEVENT_TYPE_POLY_AGENT_MESSAGEThe agent’s greeting. (If streaming: POLY_AGENT_MESSAGE_CHUNK events instead.)

​
Conversation turn (repeats)

StepDirectionEventWhat to do
8Client →EVENT_TYPE_USER_TYPING (STARTED)Optional. Send when the user begins typing.
9Client →EVENT_TYPE_USER_TYPING (STOPPED)Optional. Send when the user stops typing.
10Client →EVENT_TYPE_USER_MESSAGESend the user’s message.
11← ServerEVENT_TYPE_USER_MESSAGEEcho with server-assigned message_id. Confirms receipt.
12← ServerEVENT_TYPE_POLY_AGENT_THINKINGShow typing indicator.
13← ServerEVENT_TYPE_POLY_AGENT_MESSAGEThe agent’s response. (If streaming: POLY_AGENT_MESSAGE_CHUNK events instead.)

​
Handoff to live agent (if triggered)

StepDirectionEventWhat to do
14← ServerEVENT_TYPE_POLY_AGENT_TRIGGERED_HANDOFFInform the user they’re being connected to a human.
15← ServerEVENT_TYPE_POLY_AGENT_LEFTThe PolyAI agent has left.
16← ServerEVENT_TYPE_HANDOFF_ACCEPTEDThe live agent system accepted the request.
17← ServerEVENT_TYPE_HANDOFF_QUEUE_STATUSPeriodic. Show queue position (e.g. “You’re #3 in line”).
18← ServerEVENT_TYPE_LIVE_AGENT_JOINEDA human agent has connected. Show their name.
19Client →EVENT_TYPE_USER_MESSAGEUser messages are now routed to the human agent.
20← ServerEVENT_TYPE_LIVE_AGENT_TYPINGShow typing indicator.
21← ServerEVENT_TYPE_LIVE_AGENT_MESSAGEMessage from the human agent.
22← ServerEVENT_TYPE_LIVE_AGENT_LEFTThe human agent has left.

​
Session end

DirectionEventWhat to do
Client →EVENT_TYPE_USER_END_SESSIONUser clicks “Leave”.
← ServerEVENT_TYPE_USER_END_SESSIONEcho confirming receipt.
← ServerEVENT_TYPE_SESSION_END (REASON_USER_END)Session over. Disable input, close WebSocket.

​
Alternative endings

ScenarioWhat happens
User closes browserNo more heartbeats → session times out after ~10 minutes → SESSION_END with REASON_USER_ABANDONED
Conversation completes naturallyAgent finishes → SESSION_END with REASON_NATURAL_END
Client-managed handoffServer sends CLIENT_HANDOFF_REQUIRED instead of HANDOFF_ACCEPTED — your app routes the user to an alternative channel
Handoff failsHANDOFF_FAILED or HANDOFF_TIMEOUT — show an error and let the user try again or end the session
Connection dropsReconnect with cursor=seq:<last_sequence> using the same session_id and access_token

​
Background (send throughout)

DirectionEventFrequency
Client →EVENT_TYPE_HEARTBEATEvery 30 seconds (or per capabilities.heartbeat_interval_seconds)
← ServerEVENT_TYPE_HEARTBEATEcho of your heartbeat

​
Reconnection flow

Last modified on May 19, 2026