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

# WebSocket

> Real-time streaming communication with your agent

The WebSocket endpoint enables real-time, streaming communication with a Puppeteer agent. It supports sending messages and receiving streamed AI responses token by token.

## Connection

```
wss://api.puppeteerai.com/ws/{thread_id}
```

### Query parameters

| Parameter | Required | Description                                                        |
| --------- | -------- | ------------------------------------------------------------------ |
| `token`   | Yes      | JWT token associated with the thread.                              |
| `project` | No       | Project name. If provided, the agent is initialized on connection. |
| `version` | No       | Config version ID. Use to pin a specific config version.           |

### Example

```
wss://api.puppeteerai.com/ws/abc123?token=eyJhbGci...&project=my-project
```

## Sending messages

Send a JSON message to the WebSocket to interact with the agent:

```json theme={null}
{
  "type": "message",
  "data": {
    "message": "Hello!",
    "start_new_conversation": false,
    "puppeteer_config_name": "my-project"
  }
}
```

| Field                         | Required | Description                                                    |
| ----------------------------- | -------- | -------------------------------------------------------------- |
| `type`                        | Yes      | Must be `"message"`.                                           |
| `data.message`                | Yes      | The user's message.                                            |
| `data.start_new_conversation` | Yes      | If `true`, ends the current conversation and starts a new one. |
| `data.puppeteer_config_name`  | Yes      | The project name.                                              |

## Receiving messages

The server sends JSON messages over the WebSocket. Each message has a `type` field indicating what it is.

### Stream start

Signals the beginning of a new AI message.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "start"
  }
}
```

### Tool running

Sent when a pre-response tool is being executed. The message can be displayed as a loading indicator.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "tool_running",
    "message": "Fetching user data"
  }
}
```

| Field          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `data.message` | A user-facing description of what the tool is doing. |

### Stream chunk

A token (word or partial word) of the AI's response, delivered as it's generated.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "chunk",
    "token": "Hello",
    "index": 0
  }
}
```

| Field        | Description                                              |
| ------------ | -------------------------------------------------------- |
| `data.token` | A piece of the generated response.                       |
| `data.index` | The position of this token in the stream (zero-indexed). |

### Stream end

Signals the end of an AI message and includes the complete response.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end",
    "message": {
      "message": "Hello! How can I help you today?",
      "extras": {
        "conversation_id": "1893",
        "user_message_id": "132546d5-57fa-4f7e-a324-1d698081d2de",
        "reply_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}
```

| Field                                  | Description                                          |
| -------------------------------------- | ---------------------------------------------------- |
| `data.message.message`                 | The complete AI response.                            |
| `data.message.extras.conversation_id`  | ID of the conversation.                              |
| `data.message.extras.user_message_id`  | ID of the user message that triggered this response. |
| `data.message.extras.reply_message_id` | ID of the AI reply message.                          |

<Note>An agent may send multiple messages in a single response. Each message follows the full start → chunks → end sequence. An `end_response` event (see below) signals that all messages for the response are complete.</Note>

### End response

Sent after all messages for a response are complete. Includes response-level metadata.

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end_response",
    "extras": {}
  }
}
```

### Error

Sent if an error occurs during processing.

```json theme={null}
{
  "type": "error",
  "data": {
    "message": "Error description",
    "code": "WEBSOCKET_ERROR"
  }
}
```

## Ping / Pong

Send a ping to check if the connection is still alive. The server responds with a pong.

**Client sends:**

```json theme={null}
{
  "type": "ping"
}
```

**Server responds:**

```json theme={null}
{
  "type": "pong"
}
```

## Example interaction

**Client sends:**

```json theme={null}
{
  "type": "message",
  "data": {
    "message": "Hello there!",
    "start_new_conversation": true,
    "puppeteer_config_name": "my-project"
  }
}
```

**Server responds with a streamed reply:**

```json theme={null}
{"type": "stream", "data": {"type": "start"}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "Hi", "index": 0}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "!", "index": 1}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " How", "index": 2}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " can", "index": 3}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " I", "index": 4}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": " help", "index": 5}}
```

```json theme={null}
{"type": "stream", "data": {"type": "chunk", "token": "?", "index": 6}}
```

```json theme={null}
{
  "type": "stream",
  "data": {
    "type": "end",
    "message": {
      "message": "Hi! How can I help?",
      "extras": {
        "conversation_id": "1893",
        "user_message_id": "132546d5-57fa-4f7e-a324-1d698081d2de",
        "reply_message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  }
}
```

```json theme={null}
{"type": "stream", "data": {"type": "end_response", "extras": {}}}
```