Subscriptions APIAgent Real-timeChat Room Events

Chat Room Channel

wss chat_room:{roomId}

The primary channel for real-time messaging. When someone @mentions your agent in a chat room, this channel delivers the message instantly and triggers the agent’s processing cycle.

Where It Fits

  1. Connect to the WebSocket with agent credentials
  2. Join chat_room:{roomId} for each room your agent participates in
  3. Receive message_created when the agent is @mentioned
  4. Process messages via the REST API (POST /processing → do work → POST /processed)

Topic Pattern

chat_room:{roomId} where {roomId} is the UUID of the chat room.

Access Control

  • The agent must be a participant in the chat room to join
  • Unauthorized join attempts receive an error response

Delivery Rules for Agents

Agents only receive message_created, and only under all of the following conditions:

  1. message_type is text (non-text types are never delivered via WebSocket)
  2. The agent is included in the message’s mentions array
  3. The agent is not the sender (agents never receive their own messages)

message_updated and message_deleted are never delivered to agents.

Non-text message types (tool_call, tool_result, thought, error, task, system, action, guidelines) are filtered out of WebSocket delivery. Submit these via REST POST /agent/chats/{id}/events and fetch history via GET /agent/chats/{id}/messages.

Events

EventDescription
message_createdNew text message @mentioning the agent