Rooms and Participants

Rooms are persistent containers for conversations. Participants are the users and agents that interact within rooms, with configurable auto-respond behavior.

Rooms

A room is the top-level container where conversations happen. Every conversation belongs to a room.

Room types

Type	Behavior
Standard	Open rooms where participants can be freely added and removed. Suitable for group discussions or team channels.
Immutable (DM)	Direct message rooms with a fixed participant set. The platform computes a hash from the participant IDs to deduplicate — the same set of participants always resolves to the same room.

Creating rooms

When creating a room, you specify:

Participants — the initial set of users and/or agents
Immutable flag — whether the room is a DM-style room with fixed participants
App context — optionally, which app the room is associated with

For DM rooms, if a room already exists with the same participant set, the existing room is returned instead of creating a new one. This deduplication ensures that conversations between the same parties are always in one place.

Room lookup

The platform supports looking up rooms by:

Room ID — direct lookup
Participant set — find the room containing a specific combination of participants (using the computed hash)
App and account — find rooms associated with a specific app for a specific user

Participants

A participant is an entity (user or agent) that belongs to a room.

Adding participants

Participants are added when a room is created or through the add participant API. Each participant entry includes:

Account ID — the user or service account
Auto-respond — whether the participant's agent automatically responds to messages

Auto-respond behavior

The autoRespond flag is the key mechanism that connects conversations to AI agents:

When set to true, any message posted to the conversation triggers the participant's agent flow
When set to false, the participant is a passive member who can read and write messages but doesn't automatically react

Typically, agent participants have autoRespond: true, while human participants have it set to false.

Participant types

Type	autoRespond	Behavior
Human user	`false`	Reads and writes messages manually
AI agent	`true`	Automatically processes incoming messages through its flow
Observer agent	`false`	Present in the room but does not auto-respond (can be invoked explicitly)

Removing participants

Participants can be removed from standard rooms. In immutable (DM) rooms, the participant set is fixed at creation.

Conversation creation

Conversations are created within rooms. A conversation includes:

Room reference — which room it belongs to
Initial context — optional metadata or context for the conversation
Participants — inherited from the room, or a subset

When a conversation is created in a room that has agent participants with autoRespond enabled, the flow engine is automatically notified and starts the agent's default flow.

Caching

The conversation system uses an in-memory cache for performance:

Frequently accessed rooms and conversations are cached
Cache entries have a time-to-live (TTL) and are evicted when stale
Read operations check the cache first, falling back to the database

This caching layer ensures low-latency access for active conversations.

Real-time Messaging — how messages are delivered in real time
Agents — the AI participants in conversations
Flows — the automation triggered by conversation events
Channels — external platforms that connect to conversations

Rooms and Participants

On this page