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

# WebSocket

> Receive real-time chat responses and send tool approvals via the Nagare gateway WebSocket.

The gateway opens a WebSocket at:

```text theme={null}
ws://localhost:9832/ws
```

Agent responses (text, tool calls, approval requests...) are only sent through this channel. The REST API `/chat/send` only initiates a turn.

## Packet format

Every packet, in both directions, has the form:

```json theme={null}
{
  "event": "AuthEvent",
  "requestID": "a1b2c3",
  "data": { }
}
```

`requestID` is set by the client and echoed by the gateway in the response, helping match requests with responses.

## Usage flow

**1. Authenticate**

Send immediately after connecting:

```json theme={null}
{ "event": "AuthEvent", "requestID": "1", "data": { "token": "<TOKEN>" } }
```

The gateway returns `AuthSuccessEvent` or `AuthFailedEvent` with `{ "cause": "…" }`.

**2. Register listener for a session**

```json theme={null}
{ "event": "RegisterChatListenerEvent", "requestID": "2", "data": { "sessionID": "<SESSION_ID>" } }
```

Response: `RegisterChatListenerSuccessEvent` or `RegisterChatListenerFailEvent` (`{ cause }`).

**3. Send a message via REST**

Call `POST /api/v1/user/chat/send` with `{ sessionID, text }`. See [REST API](https://docs.nagare.smtdfc.net/en/reference/rest-api.md#chat).

**4. Receive responses**

The gateway pushes `ReceivedChatMessageEvent` events:

```json theme={null}
{
  "event": "ReceivedChatMessageEvent",
  "data": {
    "sessionID": "<SESSION_ID>",
    "channelID": "",
    "message": "{\"type\":\"TEXT_MESSAGE\",\"invokeID\":\"…\",\"role\":\"AGENT\",\"content\":\"It is 9:00\"}"
  }
}
```

The `message` field is a JSON string. See the `type` values below.

## Client-sent events

| Event | `data` | Response |
| - | - | - |
| `AuthEvent` | `{ token }` | `AuthSuccessEvent` / `AuthFailedEvent` |
| `RegisterChatListenerEvent` | `{ sessionID }` | `RegisterChatListenerSuccessEvent` / `RegisterChatListenerFailEvent` |
| `UnregisterChatListenerEvent` | `{ sessionID }` | `UnregisterChatListenerSuccessEvent` / `UnregisterChatListenerFailEvent` |
| `SubmitToolApprovalEvent` | `{ requestID, sessionID, accept }` | `SubmitToolApprovalSuccessEvent` / `SubmitToolApprovalFailEvent` |

For `SubmitToolApprovalEvent`, `data.requestID` is the ID of the approval request received in the `APPROVAL_REQUEST_MESSAGE` message.

## Message types

| `type` | Meaning | Key fields |
| - | - | - |
| `AGENT_STARTED_MESSAGE` | Agent starts processing. | `invokeID` |
| `RESPONSE_STARTED_MESSAGE` | Model starts responding. | |
| `TEXT_MESSAGE` | Text segment. | `role`, `content` |
| `REASONING_MESSAGE` | Reasoning content. | `content` |
| `TOOL_CALL_MESSAGE` | Agent calls a tool. | `name`, `args` |
| `TOOL_RESULT_MESSAGE` | Tool result. | |
| `APPROVAL_REQUEST_MESSAGE` | Tool approval required. | `requestID`, `sessionID`, `title` |
| `APPROVAL_RESPONSE_MESSAGE` | Approval result. | `requestID`, `accept` |
| `RESPONSE_COMPLETED_MESSAGE` / `RESPONSE_FAILED_MESSAGE` | Model response finished or failed. | |
| `AGENT_COMPLETED_MESSAGE` | Agent completed. | `success`, `cancel`, `duration` |
| `AGENT_ERROR_MESSAGE` | Error. | `code`, `error` |
| `CRONJOB_TRIGGER_MESSAGE` | A cron job just ran. | `prompt` |
| `CONVERSATION_SUMMARY_MESSAGE` / `COMPACT_SUCCESS_MESSAGE` | Conversation compaction result. | `summary` |

`role` accepts one of the values `AGENT`, `USER`, `SYSTEM`, `DEVELOPER`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.