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

> Nhận phản hồi trò chuyện theo thời gian thực và gửi phê duyệt công cụ qua WebSocket của Nagare gateway.

Gateway mở WebSocket tại:

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

Phản hồi của agent (văn bản, lời gọi công cụ, yêu cầu phê duyệt...) chỉ được gửi qua kênh này. REST API `/chat/send` chỉ khởi động lượt trả lời.

## Định dạng gói tin

Mọi gói tin, cả hai chiều, có dạng:

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

`requestID` do client đặt và được gateway lặp lại trong phản hồi, giúp ghép yêu cầu với phản hồi.

## Luồng sử dụng

**1. Xác thực**

Gửi ngay sau khi kết nối:

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

Gateway trả về `AuthSuccessEvent` hoặc `AuthFailedEvent` với `{ "cause": "…" }`.

**2. Đăng ký nghe một phiên**

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

Phản hồi: `RegisterChatListenerSuccessEvent` hoặc `RegisterChatListenerFailEvent` (`{ cause }`).

**3. Gửi tin nhắn qua REST**

Gọi `POST /api/v1/user/chat/send` với `{ sessionID, text }`. Xem [REST API](https://docs.nagare.smtdfc.net/reference/rest-api.md#tro-chuyen).

**4. Nhận phản hồi**

Gateway đẩy các sự kiện `ReceivedChatMessageEvent`:

```json theme={null}
{
  "event": "ReceivedChatMessageEvent",
  "data": {
    "sessionID": "<SESSION_ID>",
    "channelID": "",
    "message": "{\"type\":\"TEXT_MESSAGE\",\"invokeID\":\"…\",\"role\":\"AGENT\",\"content\":\"Bây giờ là 9:00\"}"
  }
}
```

Trường `message` là một chuỗi JSON. Xem các giá trị `type` bên dưới.

## Sự kiện client gửi

| Sự kiện | `data` | Phản hồi |
| - | - | - |
| `AuthEvent` | `{ token }` | `AuthSuccessEvent` / `AuthFailedEvent` |
| `RegisterChatListenerEvent` | `{ sessionID }` | `RegisterChatListenerSuccessEvent` / `RegisterChatListenerFailEvent` |
| `UnregisterChatListenerEvent` | `{ sessionID }` | `UnregisterChatListenerSuccessEvent` / `UnregisterChatListenerFailEvent` |
| `SubmitToolApprovalEvent` | `{ requestID, sessionID, accept }` | `SubmitToolApprovalSuccessEvent` / `SubmitToolApprovalFailEvent` |

Với `SubmitToolApprovalEvent`, `data.requestID` là ID của yêu cầu phê duyệt nhận được trong tin nhắn `APPROVAL_REQUEST_MESSAGE`.

## Loại tin nhắn

| `type` | Ý nghĩa | Trường chính |
| - | - | - |
| `AGENT_STARTED_MESSAGE` | Agent bắt đầu xử lý. | `invokeID` |
| `RESPONSE_STARTED_MESSAGE` | Mô hình bắt đầu trả lời. | |
| `TEXT_MESSAGE` | Đoạn văn bản. | `role`, `content` |
| `REASONING_MESSAGE` | Nội dung suy luận. | `content` |
| `TOOL_CALL_MESSAGE` | Agent gọi công cụ. | `name`, `args` |
| `TOOL_RESULT_MESSAGE` | Kết quả công cụ. | |
| `APPROVAL_REQUEST_MESSAGE` | Cần phê duyệt công cụ. | `requestID`, `sessionID`, `title` |
| `APPROVAL_RESPONSE_MESSAGE` | Kết quả phê duyệt. | `requestID`, `accept` |
| `RESPONSE_COMPLETED_MESSAGE` / `RESPONSE_FAILED_MESSAGE` | Mô hình trả lời xong hoặc thất bại. | |
| `AGENT_COMPLETED_MESSAGE` | Agent hoàn tất. | `success`, `cancel`, `duration` |
| `AGENT_ERROR_MESSAGE` | Lỗi. | `code`, `error` |
| `CRONJOB_TRIGGER_MESSAGE` | Một cron job vừa chạy. | `prompt` |
| `CONVERSATION_SUMMARY_MESSAGE` / `COMPACT_SUCCESS_MESSAGE` | Kết quả thu gọn hội thoại. | `summary` |

`role` nhận một trong các giá trị `AGENT`, `USER`, `SYSTEM`, `DEVELOPER`.


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