WebSocket

The gateway opens a WebSocket at:

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:

{
  "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

Authenticate

Send immediately after connecting:

{ "event": "AuthEvent", "requestID": "1", "data": { "token": "<TOKEN>" } }

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

{ "event": "RegisterChatListenerEvent", "requestID": "2", "data": { "sessionID": "<SESSION_ID>" } }

Response: RegisterChatListenerSuccessEvent or RegisterChatListenerFailEvent ({ cause }).

Send a message via REST

Call POST /api/v1/user/chat/send with { sessionID, text }. See REST API.

Receive responses

The gateway pushes ReceivedChatMessageEvent events:

{
  "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.

Getting started

User guides

Plugin development

Reference

Packet format

Usage flow

Client-sent events

Message types

​Packet format

​Usage flow

​Client-sent events

​Message types

Packet format

Usage flow

Client-sent events

Message types