DocsConversations
Conversations are the real-time messaging system on the platform. They support multi-party threads between users and agents, with rooms, participants, and message streaming.
The conversation system provides real-time messaging between users and AI agents. It handles message delivery, participant management, threading, and the connection between conversations and the flow engine.
Conversations are the primary interface through which end users interact with agents — whether through the platform UI, a web widget, or a messaging channel.
Key concepts
Rooms
A room is a persistent container for conversations. Rooms have participants (users and agents) and can contain multiple conversation threads.
Rooms can be:
- Standard — open rooms where participants can be added and removed
- Immutable/DM — direct message rooms with a fixed set of participants. The platform deduplicates DM rooms so that the same pair of participants always maps to the same room.
Conversations
A conversation is a threaded discussion within a room. Conversations maintain message history and context. When an agent's flow runs, it operates within the context of a specific conversation.
Participants
A participant is a user or agent that belongs to a room or conversation. Participants have key properties:
| Property | Description |
|---|---|
| Account | The user or service account identity |
| Auto-respond | If true, the participant's agent flow is triggered automatically when messages arrive |
| Role | The participant's role in the conversation |
When a participant with autoRespond enabled receives a message, the platform automatically starts or continues the agent's default flow.
Messages
A message is an individual communication within a conversation. Messages can contain:
- Text — plain text or formatted content
- Attachments — files, images, or other media
- Structured data — metadata or system information
Messages are delivered in real time through WebSockets and persisted for history.
How conversations connect to agents
The conversation system and the flow engine work together:
- A user creates a conversation (or opens a channel) with an agent participant
- The platform publishes a
conversation.createdevent - The flow engine picks up the event and starts the agent's default flow
- When the user sends a message, the platform publishes a
conversation.message_postedevent - The running flow receives the message and processes it (typically through an assistant step)
- The assistant generates a response that is posted back to the conversation
This cycle continues for each user message — the flow engine manages the conversation state and the assistant engine handles AI response generation.
In this section
- Rooms and Participants — managing conversation spaces and members
- Real-time Messaging — WebSocket connections and event delivery
Assets
How asset and file management works in the Bivariant platform — S3-backed storage, hierarchical folders, presigned URLs, and access control.
Rooms and Participants
Rooms are persistent containers for conversations. Participants are the users and agents that interact within rooms, with configurable auto-respond behavior.