# The session lifecycle

> boot, identify, update, shutdown, and destroy — the full lifecycle of a chat session.

Source: https://docs.useclad.ai/session-lifecycle

---

A Support Chat session moves through a predictable set of phases. After the
script loads, it goes from **`not_initialized`** to **`loading`** and then
**`ready`**. Calling [`boot()`](#bootoptions) transitions it through
**`booting`** into either an **`anonymous`** or an **`authenticated`** session,
depending on whether you supplied a user.

Once live, the realtime connection may move between **`reconnecting`** and
**`disconnected`** as network conditions change — this is handled for you
automatically. Calling [`shutdown()`](#shutdownoptions) ends the session
(**`shutdown`**), and [`destroy()`](#destroy) tears the widget down entirely
(**`destroyed`**).

You can read the current phase at any time via `chat.state`.

### `boot(options?)`

Creates or resumes a session. With no `user`, the session is **anonymous**.
With a `user`, you should supply a `tokenProvider` (see
[Identity verification](#identity-verification-jwt)).

```ts
await chat.boot({
  user: {
    id: currentUser.id,
    email: currentUser.email,
    name: currentUser.name,
  },
  company: {
    id: currentOrg.id,
    name: currentOrg.name,
    plan: currentOrg.plan,
  },
  tokenProvider: () =>
    fetch("/api/support-chat-token").then((r) => r.text()),
});
```

- Idempotent for the same identity.
- Calling `boot()` with a **different** identified user throws — call
  [`shutdown()`](#shutdownoptions) first, or use [`identify()`](#identifyoptions).

### `identify(options)`

Upgrades an anonymous session to an authenticated user (and merges anonymous
history when possible). See [Anonymous → authenticated upgrade](#anonymous--authenticated-upgrade).

### `update(options)`

Refreshes user/company traits and ephemeral page context. Safe to call on SPA
route changes; it never creates duplicate users and is rate‑limited.

```ts
await chat.update({
  user: { id: "user_123", traits: { role: "admin" } },
  company: { id: "org_456", plan: "enterprise" },
  context: { currentPage: "billing", accountHealth: "red" },
});
```

### `shutdown(options?)`

Call on **logout**. Clears user‑specific state and closes the realtime
connection. Pass `{ clearStorage: true }` to also remove anonymous/session
identifiers — important on shared computers so a previous user's conversations
don't linger.

```ts
await chat.shutdown({ clearStorage: true });
```

### `destroy()`

Removes the iframe, listeners, and timers. Persistent storage is left intact
unless you previously called `shutdown({ clearStorage: true })`.

```ts
await chat.destroy();
```