> ## 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.

# Session lifecycle

> Every event in order, from connection through session end.

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

## Connection and agent join

| Step | Direction | Event                                | What to do                                                                                         |
| ---- | --------- | ------------------------------------ | -------------------------------------------------------------------------------------------------- |
| 1    | ← Server  | `EVENT_TYPE_EVENT_BATCH`             | History replay. Flatten the `events` array. Contains at least `SESSION_START`.                     |
| 2    |           | ↳ `EVENT_TYPE_SESSION_START`         | Read `capabilities` (streaming, heartbeat interval).                                               |
| 3    | Client →  | `EVENT_TYPE_REQUEST_POLY_AGENT_JOIN` | Send to start the conversation. **New sessions only** — skip on reconnect if agent already joined. |
| 4    | ← Server  | `EVENT_TYPE_REQUEST_POLY_AGENT_JOIN` | Echo of your join request.                                                                         |
| 5    | ← Server  | `EVENT_TYPE_POLY_AGENT_JOINED`       | Agent has joined. Read `agent_name` and `agent_avatar_url` for your UI.                            |
| 6    | ← Server  | `EVENT_TYPE_POLY_AGENT_THINKING`     | Show a typing indicator.                                                                           |
| 7    | ← Server  | `EVENT_TYPE_POLY_AGENT_MESSAGE`      | The agent's greeting. (If streaming: `POLY_AGENT_MESSAGE_CHUNK` events instead.)                   |

## Conversation turn (repeats)

| Step | Direction | Event                                | What to do                                                                       |
| ---- | --------- | ------------------------------------ | -------------------------------------------------------------------------------- |
| 8    | Client →  | `EVENT_TYPE_USER_TYPING` (`STARTED`) | Optional. Send when the user begins typing.                                      |
| 9    | Client →  | `EVENT_TYPE_USER_TYPING` (`STOPPED`) | Optional. Send when the user stops typing.                                       |
| 10   | Client →  | `EVENT_TYPE_USER_MESSAGE`            | Send the user's message.                                                         |
| 11   | ← Server  | `EVENT_TYPE_USER_MESSAGE`            | Echo with server-assigned `message_id`. Confirms receipt.                        |
| 12   | ← Server  | `EVENT_TYPE_POLY_AGENT_THINKING`     | Show typing indicator.                                                           |
| 13   | ← Server  | `EVENT_TYPE_POLY_AGENT_MESSAGE`      | The agent's response. (If streaming: `POLY_AGENT_MESSAGE_CHUNK` events instead.) |

## Handoff to live agent (if triggered)

| Step | Direction | Event                                     | What to do                                                |
| ---- | --------- | ----------------------------------------- | --------------------------------------------------------- |
| 14   | ← Server  | `EVENT_TYPE_POLY_AGENT_TRIGGERED_HANDOFF` | Inform the user they're being connected to a human.       |
| 15   | ← Server  | `EVENT_TYPE_POLY_AGENT_LEFT`              | The PolyAI agent has left.                                |
| 16   | ← Server  | `EVENT_TYPE_HANDOFF_ACCEPTED`             | The live agent system accepted the request.               |
| 17   | ← Server  | `EVENT_TYPE_HANDOFF_QUEUE_STATUS`         | Periodic. Show queue position (e.g. "You're #3 in line"). |
| 18   | ← Server  | `EVENT_TYPE_LIVE_AGENT_JOINED`            | A human agent has connected. Show their name.             |
| 19   | Client →  | `EVENT_TYPE_USER_MESSAGE`                 | User messages are now routed to the human agent.          |
| 20   | ← Server  | `EVENT_TYPE_LIVE_AGENT_TYPING`            | Show typing indicator.                                    |
| 21   | ← Server  | `EVENT_TYPE_LIVE_AGENT_MESSAGE`           | Message from the human agent.                             |
| 22   | ← Server  | `EVENT_TYPE_LIVE_AGENT_LEFT`              | The human agent has left.                                 |

## Session end

| Direction | Event                                        | What to do                                    |
| --------- | -------------------------------------------- | --------------------------------------------- |
| Client →  | `EVENT_TYPE_USER_END_SESSION`                | User clicks "Leave".                          |
| ← Server  | `EVENT_TYPE_USER_END_SESSION`                | Echo confirming receipt.                      |
| ← Server  | `EVENT_TYPE_SESSION_END` (`REASON_USER_END`) | Session over. Disable input, close WebSocket. |

## Alternative endings

| Scenario                             | What happens                                                                                                              |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
| **User closes browser**              | No more heartbeats → session times out after \~10 minutes → `SESSION_END` with `REASON_USER_ABANDONED`                    |
| **Conversation completes naturally** | Agent finishes → `SESSION_END` with `REASON_NATURAL_END`                                                                  |
| **Client-managed handoff**           | Server sends `CLIENT_HANDOFF_REQUIRED` instead of `HANDOFF_ACCEPTED` — your app routes the user to an alternative channel |
| **Handoff fails**                    | `HANDOFF_FAILED` or `HANDOFF_TIMEOUT` — show an error and let the user try again or end the session                       |
| **Connection drops**                 | Reconnect with `cursor=<last_sequence>` using the same `session_id` and `access_token`                                    |

## Background (send throughout)

| Direction | Event                  | Frequency                                                           |
| --------- | ---------------------- | ------------------------------------------------------------------- |
| Client →  | `EVENT_TYPE_HEARTBEAT` | Every 30 seconds (or per `capabilities.heartbeat_interval_seconds`) |
| ← Server  | `EVENT_TYPE_HEARTBEAT` | Echo of your heartbeat                                              |

## Reconnection flow

```mermaid theme={"theme":{"light":"github-light","dark":"github-dark"}}
sequenceDiagram
    participant Client as Your App
    participant Server as PolyAI

    note over Client: Connection dropped

    Client->>Server: WebSocket connect (session_id, access_token, cursor=12)
    Server-->>Client: EVENT_BATCH (events after sequence 12)
    note over Client: Conversation state restored — continue as normal
```