Session rooms
By default every conversation with an agent is its own session: a trigger fire, a Slack thread or a portal chat each opens a new one. A room is a session that several senders share, so a person's Slack, portal and API messages, or every fire of a trigger, meet in one place and the agent remembers the earlier ones.
Enterprise module
Session rooms are the enterprise agent-rooms module, shown in the licence as Session Rooms. Without it the Session section of Build offers only Each conversation and the setting for a message that arrives while the agent works. See Licence packages.
Turn it on
Open Build → Agents, pick the agent and go to Build → Behavior → Session. The section is saved with the agent's configuration and travels with the published version: publish again for API and portal traffic.
Session scope
| Scope | What it means |
|---|---|
| Each conversation | The default, and the behavior of every agent before rooms. Every trigger fire, thread and chat opens its own session. |
| Personal room | One room per person: their Slack, portal and API messages meet in it. |
| Workspace room | One room in the project. Triggers, Slack, webhooks and the portal all land in it. |
| Room by key | One room per value of a key: one per trigger, or one per value of a field of the incoming event (for example one per release). The Room key is metadata.<name>, variables.<name> or event.<path>; an event without the field opens its own session. |
| Trigger room | Each trigger has its own room; every fire remembers the previous one. The sessions list names a room by how it was made: Trigger room, Room by key or Room made by hand. |
With a scope other than Each conversation the section also shows the settings below. Room rotation, Who may write, Room sharing and Invites apply once you pick a room scope.
Room rotation
Open a new room: Never, After it sits idle (Hours idle, 1 to 2160; 24 by default), Every day at 00:00 UTC, or Only when somebody closes it. Hand the new room a summary of the previous one carries the thread over (on by default). A person with the right can Close room on the room's tab; the transcript stays and the next message opens a fresh room.
Who may write
Only the room owner, Project members, or Selected people and groups. The owner is whoever the room belongs to: the person in a personal room, the agent owner in a workspace room, the trigger owner in a trigger room. Somebody not allowed who writes from Slack is told they cannot write in this session; the message does not reach the agent. Invited people can always write.
A message that arrives while the agent works
This setting (A message that arrives while the agent works) applies to each conversation too.
| Choice | What happens |
|---|---|
| Take it in (default, recommended) | When the current step ends the agent sees the message; it answers briefly and carries on, or changes course. |
| Queue it | The message waits and starts the next turn when this one ends. |
| Refuse it | The sender is told the agent is busy (the behavior before rooms). |
Under Room sharing: Most messages taken in per turn (10 by default, at most 50), Tell the sender the message was received, and The sender may edit or withdraw a message before the agent sees it (both on by default).
Invites
| Setting | Default |
|---|---|
| Participants may invite other people | On |
| The agent may invite people (session_invite tool) | Off |
| Most invited people per room | 5 |
| Default role | Member |
Roles are Member (writes; a message sent while the agent works is taken in), Approver (writes like a member; who may approve a tool call is still set under Approvals & questions) and Viewer (reads, cannot write). An invite can last until the room closes, 24 hours, 7 days or a number of hours. Only people of the project can be invited.
People can open a room from a conversation (Add people), off by default: in the portal a person adds people to their own conversation, a new room opens with a copy of it, and the conversation itself stays theirs alone.
API calls may pick another scope lets a Runs or Responses call ask for a scope other than the agent's own; see Session options over the API.
A trigger can override it
A trigger has its own Session setting: Use the agent's setting, or Change it for this trigger (a scope, and what a run that fires while the agent works does). For example a CRM webhook whose every event gets its own session.
Agents that answer from a knowledge base
An agent that answers from a knowledge base (its own, or through a sub-agent it calls) keeps its sessions personal, whatever its settings say: each conversation is its own session, or each person keeps one long session. Nobody else takes part and nobody is invited, because what the agent reads for one person is never shown to anybody else. A saved room scope is kept and applies again if the knowledge bases are removed. See Knowledge base access control.
The room
A session in a room has a Room tab: its state (Working, Idle, Waiting for a person, Closed), the Participants with their roles, the Routes tied to it (a Slack, Teams or e-mail thread, a webhook subject, an agent session, the portal) and the messages Waiting for the agent. The sender of a waiting message can Edit or Withdraw it until the agent takes it in. In the sessions list, the Rooms filter shows room sessions.
Who owns a session depends on its scope: in a room the session belongs to the room, and its participants write to it. The permissions in Who can do this still decide what other people may do with a session they did not start.
In a portal the same rooms appear under Rooms and the messages received during a running turn under Inbox; see the portal user guide.
Session options over the API
A run request and POST /responses accept a session object. Every field is optional:
| Field | Values |
|---|---|
session.scope | conversation, user, workspace or key. Chooses the session of a call that names none (session_id, conversation, previous_response_id). |
session.key | The room key itself (a value such as a ticket id), with scope: "key" only. |
session.when_busy | steer, queue, agent or reject: what the call's message does when the session's agent is already working. |
A shared scope other than the agent's own needs API calls may pick another scope, else 403 session_scope_not_allowed. Without the module a shared scope is 400 session_scope_unavailable.
A message for a busy session is refused with 409 agent_run_conflict unless the call opts in with when_busy (on the runs API a room also follows its agent's setting without it). The agent's setting is the ceiling: an agent that takes no message while it works answers 409 with details.when_busy: "off" whatever is asked. A waiting message is answered 202 with a session.input object; 409 attachments_not_queued when it carries files, 429 session_queue_full when the waiting list is full. Handling a waiting message is described in Waiting messages; the events are in Session events.

