WebSocket Chat

Use the per-agent WebSocket for foreground, token-by-token chat. One authenticated socket can multiplex turns from many chats, and a turn continues running if the socket disconnects.

Connection

Keep the API hostname configurable:

wss://api.trellis.sh/v1/agents/{agent_id}/chats/ws

Read agent_id from Create Chat or Get Chat. A legacy chat can return null; fall back to your organization’s configured published agent UUID and verify it against List Agents. Do not infer it from the display name or is_trellis_default flag. The legacy row remains null, so apply the configured fallback on every load. The server validates the agent during setup:

Close code	Meaning
`4004`	Agent is unknown to the organization, or `{agent_id}` is not a UUID (`AGENT_NOT_FOUND`)
`4003`	Agent exists but its status is not `published` (`AGENT_NOT_PUBLISHED`)

Do not put the JWT in a ?token= query parameter. It is rejected with code 4400 because query strings can be written to access logs.

Authentication

Authenticate either on the upgrade request or in the first frame.

Authorization header
First frame

import websockets

async with websockets.connect(
    "wss://api.trellis.sh/v1/agents/AGENT_ID/chats/ws",
    additional_headers=[("Authorization", "Bearer YOUR_TOKEN")],
) as ws:
    ...

const ws = new WebSocket(
  "wss://api.trellis.sh/v1/agents/AGENT_ID/chats/ws",
);
ws.onopen = () => {
  ws.send(JSON.stringify({ action: "authenticate", token: "YOUR_TOKEN" }));
};

Success returns a bare frame:

{"event":"authenticated","data":{"status":"ok","agent_id":"AGENT_ID"}}

A missing, invalid, or expired token closes with 4001. Malformed JSON in the first frame closes with 4002.

Connection and submission limits

At most three external sockets may be open for one authenticated member. A fourth receives a bare error and closes with 4429:

{"event":"error","data":{"code":"WS_CONNECTION_CAP","retryable":false}}

The submission budget is also member-scoped and shared across transports: WebSocket send_message, WebSocket edit_message, and REST POST .../turns consume one combined budget of 10 per minute and 3 per 10 seconds. Separate sockets or newly minted JWTs for the same member do not create new budgets. Rejected submissions count in both windows. Excess WebSocket submissions receive an enveloped pre-turn error:

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":null,"seq":0,"event":"error","data":{"code":"RATE_LIMIT","retryable":true,"retry_after_seconds":7}}

ping, interrupt, resume, and delete_message do not consume this submission budget.

Keepalive

The server sends a bare heartbeat every 10 seconds for the socket’s entire lifetime:

{"event":"heartbeat","data":{"ts":1786212000.123}}

You may also send {"action":"ping"}. The server replies {"event":"pong","data":{}}.

Frame envelope

Every frame associated with a turn is wrapped as:

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":4,"event":"text_delta","data":{"content":"..."}}

string | null

Chat that owns the turn. It can be null on an error raised before the request identified a chat.

string | null

Durable turn ID. Submission errors sent before turn_accepted use null; resume and other control errors can echo a client-supplied turn ID.

integer

Monotonic sequence within one turn. turn_accepted and request/control errors outside an accepted turn use 0; replayable turn frames start at 1.

string

Event name.

object | string

Event-specific payload.

Partition by turn_id and order/deduplicate by (turn_id, seq). One socket can stream several chats concurrently. Bare control frames have only {event, data}: authenticated, heartbeat, pong, deleted, the interrupt acknowledgement named interrupted, and handshake/invalid-JSON/unknown-action/connection-cap errors. The enveloped interrupted event is a different frame: it terminalizes a cancelled turn.

Actions

Action	Required fields	Optional fields
`send_message`	`chat_id`, `message`	`client_request_id`, `model`, `integration_id`, `upload_ids`, `saved_query_id`, `parameters`, `scoped_project_ids`, `project_id`; compatibility fields are described below
`edit_message`	`chat_id`, `message_id`, `content`	`client_request_id`, `model`, `integration_id`, `scoped_project_ids`; legacy datasource aliases are also accepted
`delete_message`	`message_id`	none
`interrupt`	`turn_id`	none; `chat_id` is ignored
`resume`	`chat_id`, `turn_id`	`last_seq` (default `0`)
`ping`	none	none

Unknown actions receive a bare error; the socket remains open.

Send a message

string

required

Must be "send_message".

string

required

Existing, member-owned chat. Missing returns MISSING_CHAT_ID; unknown/unowned returns CHAT_NOT_FOUND; a non-null binding to another agent returns AGENT_CHAT_MISMATCH.

string

required

Non-empty user text.

string

Optional on WebSocket, but strongly recommended. Length 1–128. Retrying the same semantic payload with the same ID reattaches to the original turn; reusing it for a different payload returns IDEMPOTENCY_CONFLICT. Generate a new ID when any generation input changes.

string

Model override for this turn. Populate choices from List Models.

string

Database integration for this and subsequent turns. A valid change persists on the chat.

string[]

IDs returned by Upload Files.

string

Execute a stored query before the agent answers. An integration must be bound.

object

Saved-query parameters as string values.

string[]

Project scope to persist on the chat. Omit the field to retain stored scope; send [] to clear it. In request order, the server keeps the first occurrence of each valid, organization-owned, permitted project and persists at most the first two surviving IDs. Duplicate, malformed, unknown, out-of-organization, non-permitted, and additional IDs are silently discarded.

string

Legacy shorthand for a one-element scoped_project_ids. It is ignored when scoped_project_ids is present.

{
  "action": "send_message",
  "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "message": "How many orders were placed last month?",
  "client_request_id": "mobile-20260808-7f4f1fca",
  "integration_id": "INTEGRATION_ID",
  "model": "claude-sonnet-5",
  "scoped_project_ids": []
}

Compatibility-only send fields

The handler also reads these fields, but new external clients should avoid them:

Field	Behavior
`connection_id`, `connection_type`	Legacy datasource aliases. `connection_id` acts as `integration_id` unless `connection_type` is `"project"`. Prefer `integration_id`.
`attached_files`	Internal project-file references. The external API does not expose the file IDs needed to construct them; use `upload_ids`.
`open_schedule`	Internal schedule-panel handoff. A non-object value is rejected before a turn is minted.
`voice_mode`	Does not enable voice on this socket; it only changes the idempotency fingerprint.
`title`	Accepted but does not retitle an existing chat. Set the title when creating/renaming the chat or allow send auto-titling.
`include_tool_events`	Ignored. Tool events are always emitted when tools run.

A second turn on the same chat is rejected with TURN_ALREADY_RUNNING until the running row reaches a terminal state.

Idempotent acceptance

An accepted send or edit begins with an enveloped acknowledgement at sequence zero:

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":0,"event":"turn_accepted","data":{"turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","user_message_id":"b3ebae7f-e265-47e4-92dd-344d396f0c33","status":"in_progress"}}

Persist the turn_id immediately. A duplicate client_request_id with an identical payload returns the original turn_accepted, then replays/reattaches to that turn rather than writing another user message.

Event reference

All events in this table use the turn envelope.

Event	`data`	Notes
`turn_accepted`	`{turn_id, chat_id, user_message_id, status}`	Sequence 0. `status` uses public values.
`chat_metadata`	`{id, user_message_id}` or `{id, title}`	Initial metadata; a default title can be regenerated before the terminal event.
`processing`	`{status: "starting"}`	Initial processing marker.
`text_delta`	`{content, depth?, skill?, segment_id?}`	Incremental content. Append in sequence order.
`thinking`	`{content, segment_id?}`	Extended-thinking content.
`segment_verdict`	`{segment_id, kind}`	Classifies a completed text segment; `kind` is `"reasoning"` or `"answer"`.
`tool_call`	`{tool, args, tool_call_id?, depth?, skill?, message_id?}`	Tool start. `message_id` is optional.
`tool_result`	`{tool, output, tool_call_id?, depth?, skill?, message_id?}`	Normal result shape. Explicit saved queries are the exception below.
`tool_message`	string or `{content, depth, skill}`	Intermediate narration.
`scope_notice`	`{project_ids, project_names}`	Effective project scope.
`panel_open`	`{panel_id, entity_id, entity_version, type, state, tool_call_id, chat_message_id}`	Typed panel state.
`message`	`{content, id, timestamp}`	Terminal success.
`error`	`{error, code, retryable, debug_id}`	Terminal turn failure after `turn_accepted`. Other error contexts have different payloads; see Error frames.
`interrupted`	`{content}`	Terminal cancellation. Enveloped; distinct from the bare ack.
`resume`	`{alive, status, last_seq, reason}`	Replay fallback; reconcile via REST.

The success event is named message, not final.

Two `tool_result` shapes

Normal agent tool results are self-describing. The result body is data.output:

{
  "tool": "data_analytics__execute_sql",
  "output": {
    "kind": "table",
    "columns": [{"name": "order_count", "type_hint": "number", "sql_type": "int"}],
    "rows": [[1523]],
    "row_count": 1,
    "truncated": false,
    "integration_id": "INTEGRATION_ID",
    "success": true
  },
  "tool_call_id": "call_01",
  "message_id": "c3f0fe73-1aa3-440b-b50d-03527415800f"
}

An explicit saved_query_id produces a synthetic unwrapped result instead:

{
  "rows": [{"order_count": 1523}],
  "row_count": 1,
  "truncated": false
}

This saved-query shape has no tool, output, tool_call_id, or message_id, and its rows are objects rather than positional arrays. Decode with:

const resultBody = Object.hasOwn(event.data, "output")
  ? event.data.output
  : event.data;

The paired synthetic tool_call also has no tool_call_id; it arrives immediately before the result.

Example turn

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":0,"event":"turn_accepted","data":{"turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","user_message_id":"b3ebae7f-e265-47e4-92dd-344d396f0c33","status":"in_progress"}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":1,"event":"chat_metadata","data":{"id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","user_message_id":"b3ebae7f-e265-47e4-92dd-344d396f0c33"}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":2,"event":"processing","data":{"status":"starting"}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":3,"event":"tool_call","data":{"tool":"data_analytics__execute_sql","args":{"sql":"SELECT COUNT(*) AS order_count FROM analytics.project_summary WHERE period = (SELECT MAX(period) FROM analytics.project_summary)"},"tool_call_id":"call_01","message_id":"01f32bd2-8a3a-4f02-8604-88dc5f2aac3b"}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":4,"event":"tool_result","data":{"tool":"data_analytics__execute_sql","output":{"kind":"table","columns":[{"name":"order_count","type_hint":"number","sql_type":"int"}],"rows":[[1523]],"row_count":1,"truncated":false,"integration_id":"INTEGRATION_ID","success":true},"tool_call_id":"call_01","message_id":"c3f0fe73-1aa3-440b-b50d-03527415800f"}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":5,"event":"text_delta","data":{"content":"There were 1,523 orders."}}
{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":6,"event":"message","data":{"content":"There were 1,523 orders.","id":"69fd9d75-7141-4584-b8be-7dd6a3073459","timestamp":"2026-08-08T18:00:03+00:00"}}

Interrupt a turn

Send the turn_id captured from turn_accepted:

{"action":"interrupt","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b"}

The first interrupted frame is a bare acknowledgement that cancellation was requested:

{"event":"interrupted","data":{"turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","status":"interrupted"}}

It is not terminal and does not prove the producer has stopped. Keep reading until the turn emits its separate enveloped terminal:

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":17,"event":"interrupted","data":{"content":"Partial answer persisted so far"}}

The terminal frame’s content is the authoritative persisted partial answer. Cancellation is cooperative and can take a few seconds across instances. Omitting turn_id returns an enveloped pre-turn error with {"error":"turn_id is required"}; an unknown/unowned turn returns the generic {"error":"Turn not found"}.

Resume after a disconnect

A disconnect does not cancel a turn. Treat Get Chat as the correctness path after a disconnect; exact WebSocket replay is an optimization for recovering intervening event frames.

Call GET /v1/chats/{chat_id} and replace local transcript rows with messages.
Render active_turn.partial_content as the current assistant text and replace the local cursor with running_turn_last_seq. The snapshot contains canonical content through that watermark, so discard any older local partial buffer instead of concatenating it.
If running_turn_id still identifies the turn, keep the composer locked, reconnect, and request frames strictly after that refreshed cursor:

{"action":"resume","chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","last_seq":7}

When exact replay is available, the server sends every frame with seq > last_seq, then live-tails the turn. Deduplicate by (turn_id, seq). Do not rely on exact replay as the only recovery path: the server can instead send a fallback resume control frame:

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":91,"event":"resume","data":{"alive":true,"status":"running","last_seq":91,"reason":"gap"}}

reason is gap, degraded, or expired. status is the raw durable value running, done, error, or cancelled. When this frame arrives, that subscription is finished; waiting on it loses the answer. Repeat the REST reconciliation above immediately, then resume from the new running_turn_last_seq after backoff if running_turn_id still matches. is_processing: false alone does not unlock the chat; it is only a liveness hint. When running_turn_id becomes null, the terminal persisted rows are in messages; stop resuming and unlock the composer. The server may also send resume without a reconnect if a slow client falls behind. Use the same reconciliation path.

Edit a user message

Editing deletes the target user message and all later messages, inserts the replacement user message, and starts a new durable turn. Only an existing user message can be edited.

string

required

Must be "edit_message".

string

required

Chat containing the message.

string

required

Existing user-message ID.

string

required

Non-empty replacement text.

string

Optional 1–128 character idempotency key. Strongly recommended.

string

Model override for the regenerated turn.

string

Datasource for the regenerated turn; persists on the chat.

string[]

Omit to retain stored scope; send [] to clear it. The server preserves first-occurrence request order, silently filters duplicate, invalid, unknown, out-of-organization, and non-permitted IDs, and persists at most the first two surviving IDs.

connection_id and connection_type are accepted as legacy datasource aliases. No other send-only fields are read: an edit cannot add or change upload_ids, attached_files, a saved query, parameters, project_id, or an internal schedule handoff.

{
  "action": "edit_message",
  "chat_id": "9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb",
  "message_id": "b3ebae7f-e265-47e4-92dd-344d396f0c33",
  "content": "How many orders were placed in March?",
  "client_request_id": "edit-20260808-310b8ac4",
  "integration_id": "INTEGRATION_ID",
  "scoped_project_ids": []
}

Edits share the submission throttle, idempotency behavior, turn_accepted acknowledgement, and one-running-turn rule with sends. The destructive truncation and turn acceptance are atomic: a rejected edit does not truncate the transcript.

Delete a message

Deleting truncates the message and everything after it:

{"action":"delete_message","message_id":"c3f0fe73-1aa3-440b-b50d-03527415800f"}

Success returns a bare frame:

{"event":"deleted","data":{"message_id":"c3f0fe73-1aa3-440b-b50d-03527415800f"}}

This is also available over REST via Delete Message.

Error handling

Close codes

Code	Meaning
`4400`	JWT supplied in the URL
`4001`	Authentication required or invalid/expired token
`4002`	Malformed JSON in the first authentication frame
`4003`	Agent is not published
`4004`	Agent not found or malformed agent UUID
`4429`	Three-connection member cap reached
`1011`	Internal socket failure

Error frames

WebSocket errors have three distinct wire contexts:

Socket setup and control errors are bare {event, data} frames with no chat/turn envelope. Authentication, agent setup, invalid JSON, unknown-action, and connection-cap failures use this context.
Request and control errors outside an accepted turn can be enveloped with seq: 0. Submission errors use turn_id: null; resume and other control errors can echo the supplied turn_id. Examples include a missing message, invalid idempotency key, rate limit, chat lookup failure, or rejected resume.
Turn failures after turn_accepted are terminal turn frames with a non-null turn_id and positive seq. On the external socket, their data is normalized to error, code, retryable, and debug_id.

There is no universal error payload across all three contexts. Bare and pre-acknowledgement errors can omit code, retryable, debug_id, or human-readable error; inspect fields defensively.

{"chat_id":"9f0ac8f2-7a22-4ec8-a778-b0b1b83a86bb","turn_id":"26e53cf2-b12d-4a2a-a3b7-5382a87f8f5b","seq":8,"event":"error","data":{"error":"The datasource could not be reached.","code":"DATABASE_CONNECTION_FAILED","retryable":true,"debug_id":"4a8c0ae6"}}

When code is present, branch on it rather than the human-readable error. Retry only when retryable is explicitly true, include debug_id in support requests when present, and treat missing or unknown codes as non-retryable.

Code	Retryable	Typical cause
`INTEGRATION_NOT_FOUND`	no	Datasource is not accessible to the organization
`INTEGRATION_NOT_CONFIGURED`	no	No datasource is bound for an operation that requires one
`DATABASE_CONNECTION_FAILED`	yes	Datasource network/pool failure
`DATABASE_QUERY_FAILED`	no	Query execution error
`DATABASE_QUERY_TIMEOUT`	yes	Query exceeded its timeout
`TOOL_TIMEOUT`	yes	Tool execution exceeded its timeout
`SERIALIZATION_ERROR`	no	Result could not be encoded
`VALIDATION_ERROR`	no	Invalid request data
`ACCESS_DENIED`	no	Caller lacks access
`RATE_LIMIT`	yes	Shared member submission throttle or upstream rate limit
`MODEL_ERROR`	yes	Model-provider failure
`AGENT_RETRY_EXHAUSTED`	yes	Agent could not recover from repeated invalid tool calls
`INTERNAL_ERROR`	yes	Unclassified server failure
`MISSING_CHAT_ID`	no	Send omitted `chat_id`
`CHAT_NOT_FOUND`	no	Chat/turn is unknown or outside caller scope
`AGENT_CHAT_MISMATCH`	no	Non-null chat binding differs from socket agent
`INVALID_CLIENT_REQUEST_ID`	no	Idempotency key is empty, non-string, or over 128 characters
`IDEMPOTENCY_CONFLICT`	no	Same client request ID reused for a different semantic payload
`TURN_ALREADY_RUNNING`	no	Chat already owns an in-progress turn
`WS_CONNECTION_CAP`	no	Member already has three external sockets
`AGENT_NOT_FOUND`	no	Agent path is malformed or unknown
`AGENT_NOT_PUBLISHED`	no	Agent is not published

Overview

Authentication

Agents

Datasources

Saved Queries

Models

Chats

Artifacts

Jobs

Voice

Audio

User Memories

Organization Rules

Admin

Connection

Authentication

Connection and submission limits

Keepalive

Frame envelope

Actions

Send a message

Compatibility-only send fields

Idempotent acceptance

Event reference

Two `tool_result` shapes

Example turn

Interrupt a turn

Resume after a disconnect

Edit a user message

Delete a message

Error handling

Close codes

Error frames

​Connection

​Authentication

​Connection and submission limits

​Keepalive

​Frame envelope

​Actions

​Send a message

​Compatibility-only send fields

​Idempotent acceptance

​Event reference

​Two tool_result shapes

​Example turn

​Interrupt a turn

​Resume after a disconnect

​Edit a user message

​Delete a message

​Error handling

​Close codes

​Error frames

Connection

Authentication

Connection and submission limits

Keepalive

Frame envelope

Actions

Send a message

Compatibility-only send fields

Idempotent acceptance

Event reference

Two `tool_result` shapes

Example turn

Interrupt a turn

Resume after a disconnect

Edit a user message

Delete a message

Error handling

Close codes

Error frames