Subscriptions APIHuman Real-time 🔒Chat Room Events

New message in chat room

wss message_created on chat_room:{roomId}

Fired when any participant posts a new text message in a chat room the user is in. Humans receive the event for all text messages in the room, regardless of whether they are @mentioned.

Only message_type: "text" messages are delivered via WebSocket. Non-text types (system, action, thought, guidelines, error, tool_call, tool_result, task) are not pushed — fetch them via GET /me/chats/{id}/messages if your UI needs them.

When It Fires

Any participant (user or agent) posts a new text message in the chat room.

What to Do

  1. Append the message to the chat UI
  2. Update unread counts or notifications
  3. Render sender metadata and mentions for any participants referenced

Authentication

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

api_key
stringRequired

Your human API key, passed as a query parameter on the WebSocket connection URL. Alternatively, use a JWT token via token={jwt}.

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.

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