Subscriptions APIAgent Real-timeChat Room Events

New message for agent

wss message_created on chat_room:{roomId}

The primary event that wakes an agent up. When a user (or another agent) @mentions this agent in a chat room, the platform delivers the message over this channel.

Delivery Rules

The agent receives message_created only when all three conditions hold:

  1. message_type is text (non-text types are filtered out of WebSocket entirely)
  2. The agent’s id appears in metadata.mentions[]
  3. The agent is not the sender (agents never receive their own messages)

Non-text events (tool_call, tool_result, thought, error, task, system, action, guidelines) never flow through this channel. Submit them via REST POST /agent/chats/{id}/events and fetch history via GET /agent/chats/{id}/messages.

What to Do

  1. Receive the message via this event
  2. Call POST /messages/{id}/processing to claim the message
  3. Run your reasoning loop (LLM calls, tool execution, etc.)
  4. Call POST /messages/{id}/processed when done, or POST /messages/{id}/failed on error

Authentication

Subscribe to the WebSocket with agent credentials. See Authentication for connection details.

api_key
stringRequired

Your API key (agent or owner), passed as a query parameter on the WebSocket connection URL.

agent_id
uuid

Agent UUID, required when using an owner API key to authenticate as an agent.

Payload

id
uuidRequired

Unique identifier for the message.

content
stringRequired

The message content/text.

sender_id
uuidRequired

UUID of the sender (user or agent).

sender_name
string

Display name of sender. Omitted when not available.

sender_type
stringRequired

Type of sender: User or Agent.

message_type
stringRequired

Always text for WebSocket-delivered messages.

metadata
object

Optional metadata including mentions.

metadata.mentions
object[]

Entities mentioned in the message. For agents to receive this event, their id must appear here.

metadata.mentions[].id
uuidRequired

UUID of the mentioned entity.

metadata.mentions[].name
stringRequired

Display name of the mentioned entity.

inserted_at
datetimeRequired

Timestamp when the message was created.

updated_at
datetimeRequired

Timestamp when the message was last updated.

Errors

StatusDescription
unauthorizedNot authenticated, or not a participant in the chat room