> ## Documentation Index
> Fetch the complete documentation index at: https://docs.layercode.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How connecting to Layercode works

> Visual diagram of how your app connects to Layercode

## Fresh Page Load (New Conversation)

```mermaid theme={null}
sequenceDiagram
    participant UI as Browser UI
    participant SDK as LayercodeClient (JS SDK)
    participant Auth as POST /v1/agents/web/authorize_session
    participant DB (sessions + conversations)
    participant WS as GET /v1/agents/web/websocket
    participant Pipeline as Voice Pipeline Worker

    UI->>SDK: instantiate client.connect()
    SDK->>Auth: POST { agent_id, metadata, sdk_version }
    Auth->>DB: validate pipeline/org and insert conversation + session
    DB-->>Auth: client_session_key + conversation_id
    Auth-->>SDK: { client_session_key, conversation_id, config }
    SDK->>WS: WebSocket upgrade ?client_session_key=...
    WS->>DB: lookup session via client_session_key
    WS->>Pipeline: start voicePipeline(session)
    Pipeline-->>SDK: streaming audio + events
    SDK-->>UI: onConnect({ conversationId, config })
```

* `authorizeSession` creates the conversation record when no `conversation_id` exists, allocates a session row, and returns a 1-hour `client_session_key`.
* The browser client must include a valid bearer token (API key) when proxying to the authorize endpoint.

***

## Page Load With Stored Conversation

```mermaid theme={null}
sequenceDiagram
    participant UI as Browser UI (resuming)
    participant SDK as LayercodeClient
    participant Auth as POST /v1/agents/web/authorize_session
    participant DB (sessions + conversations)
    participant WS as GET /v1/agents/web/websocket
    participant Pipeline as Voice Pipeline Worker

    UI->>SDK: client.connect()
    SDK->>Auth: POST { agent_id, conversation_id }
    Auth->>DB: fetch conversation + pipeline, create new session key
    DB-->>Auth: verify ownership, persist session
    Auth-->>SDK: { client_session_key, conversation_id, config }
    SDK->>WS: WebSocket upgrade using new client_session_key
    WS->>DB: validate session + pipeline balance
    WS->>Pipeline: resume conversation context
    Pipeline-->>SDK: stream resumes with existing turn state
```

* The SDK automatically reconnects to an existing conversation if a `conversationId` is cached.
* To start fresh, create a new client with `conversationId = null`.
* Re-authorizing rotates the `client_session_key`, so old WebSocket URLs stop working once a resume happens.

***

## Network Drop and Manual Reconnect

```mermaid theme={null}
sequenceDiagram
    participant UI as Browser UI
    participant SDK as LayercodeClient
    participant WS as WebSocket Connection
    participant Auth as POST /v1/agents/web/authorize_session
    participant DB (sessions + conversations)
    participant Pipeline as Voice Pipeline Worker

    WS-xSDK: network drop / close event
    SDK->>SDK: _performDisconnectCleanup() (status=disconnected)
    SDK-->>UI: onDisconnect() (show reconnect)
    UI->>SDK: user clicks reconnect
    SDK->>Auth: POST { agent_id, conversation_id }
    Auth->>DB: create fresh session + ensure balance
    Auth-->>SDK: { client_session_key, conversation_id, config }
    SDK->>WS: establish new WebSocket ?client_session_key=...
    WS->>Pipeline: restart transport against same conversation
    Pipeline-->>SDK: continue streaming and emit onConnect({ conversationId, config })
```

* Device listeners, VAD, and amplitude monitors are rebuilt on reconnect.
* The cached `conversationId` persists, so the next `authorize` call resumes seamlessly.
* To force a fresh run after a drop, instantiate a new client with `conversationId = null` before reconnecting.