Agent sessions

Agent sessions let users manage their conversations with your agent in a single place. From the user's perspective, sessions surface a status (one of "processing", "active", "suspended", or "closed"), a title for recall, and a stop button while the agent is working. Users see their subscribed sessions in chronological order and can pin, rename, or archive them.

This page documents thread-based agent sessions, which are sessions scoped to a single thread in a conversation, like a channel or DM.

Only apps declared as agents in the app settings (which requires the assistant:write scope) can create sessions. The chat:write scope is also required to manage thread-based sessions.

Available methods

Method	Description
`agents.sessions.setStatus`	Set an agent session's lifecycle status, creating the session if needed.
`agents.sessions.rename`	Rename an agent session.

Properties of an agent session

Property	Required	Description
`channel_id`	Required	The channel or DM the session thread is in.
`thread_ts`	Conditional	Timestamp of the thread's root message that the session is scoped to. Required for thread-based sessions.
`status`	Optional	The current lifecycle state. One of: `active`, `suspended`, `processing`, or `closed`. Set with the `agents.sessions.setStatus` method.
`title`	Optional	A user-friendly title that helps users recall past interactions. If not provided, Slack falls back to a default based on message contents. Set with the `agents.sessions.rename` method, or on creation via the `agents.sessions.setStatus` method.
`initiator_user_id`	Conditional	The user that initiated the session. Required when creating a new session but ignored on updates. Usually the human user the agent is responding to, but it may be the agent's bot user ID if the agent proactively started the session.

Status values

Status	Meaning
`active`	The agent is alive and ready for the next prompt or task.
`processing`	The agent is working on a user's task. A stop button is shown to the user.
`suspended`	The agent cannot make progress until the user intervenes, for example when the agent needs user clarification or a tool approval.
`closed`	The agent has closed the session and will no longer respond on it.

Session lifecycle

Create sessions when your agent sends messages or signals its intent to reply to a user. The primary API method for managing a session's status is the agents.sessions.setStatus method, which creates the session if it doesn't exist and updates its status if it does. Use the agents.sessions.rename method to change a session's title.

A typical flow:

A user sends a message to your agent in a thread (in a channel or DM).
Your app calls the agents.sessions.setStatus API method with status: "processing" (and, on creation, an optional title).
Your app does its work, posting messages with the chat.postMessage API method or streaming with the chat.startStream API method.
When the agent finishes and is ready for the next prompt, it calls the agents.sessions.setStatus API method with status: "active".
If the agent needs user input to continue, it sets status: "suspended".
When the conversation is complete, the agent sets status: "closed".

Processing status

When a session is in processing, Slack shows a stop button and a loading UX to the user.

Session timeouts

Sessions in processing time out after one hour and automatically transition to active. Setting processing again restarts the one-hour timer. Apps can periodically re-send processing to reset the timer and keep the session alive during long-running operations.

Loading UX

While a session is in processing, Slack shows a standard "Working…" loading UX. Custom loading messages are not supported.

Customizing your agent's appearance

You can override the agent's icon and display name with the icon_emoji, icon_url, and username parameter. These require the chat:write.customize scope and remain in effect until you clear them (by passing null) or set a different value. They are not cleared automatically on status transition.

These overrides apply only to the session metadata (the loading UX and session surface), not the messages. To keep a consistent name and icon on the messages your agent sends, set them via the corresponding method, either the (chat.postMessage method or the chat.startStream method.

POST /api/agents.sessions.setStatus
{
  "channel_id": "C123ABC",
  "thread_ts": "1717171717.123456",
  "status": "processing",
  "title": "Scuba diving research",
  "icon_emoji": ":robot_face:",
  "username": "Custom Agent Name"
}

Messaging interactions

Agent sessions integrate with the Slack streaming API methods for a streamlined experience:

The chat.startStream method creates a session if one doesn't exist, and sets the session status to processing. It requires channel and thread_ts (the thread to stream into). When a stream creates a new session, the initiator_user_id is set to the recipient_user_id.
```
POST /api/chat.startStream
{
  "channel": "C123ABC",
  "thread_ts": "1717171717.123456",
  "markdown_text": "I'll research scuba diving and create a canvas for you..."
}
```

The chat.stopStream method can set the session status via the session_status parameter (defaults to active). If a stream times out, the session status is set to active.

POST /api/chat.stopStream
{
  "channel": "C123ABC",
  "ts": "1717171717.654321",
  "markdown_text": "What is the intended audience? Experienced diver or newbie?",
  "session_status": "suspended"
}

Agent sessions do not require using the streaming API methods. You can instead use the agents.sessions.setStatus method with the chat.postMessage method and the chat.update method. However, when not using the streaming API methods, your app must call the agents.sessions.setStatus method to manage the session status, and the agents.sessions.rename method to manage the title, as there is no implicit state management.

Stopping a session

Slack will display a native stop button to the user while the session is in processing status. All apps that implement sessions must support stop.

When the user clicks the stop button, your app will receive an agent_session_stopped event. Your app should:

Stop any in-progress work for the given channel and thread.
Clean up resources and confirm to the user that work has stopped.
Set the session status away from processing using either agents.sessions.setStatus or chat.stopStream.

The session status will not update automatically when the user clicks stop. Your app is responsible for transitioning the status.

// agent_session_stopped event payload
{
  "channel": "C123ABC456",
  "event_ts": "1783536983.783769",
  "team_id": "T0123ABC456",
  "thread_ts": "1782234671.392669",
  "message_ts": "1782234987.693923",
  "type": "agent_session_stopped",
  "user": "U123ABC456"
}

Renaming a session

Users may change the title of a session at any time, even if the agent previously set it. When this happens, your app receives an agent_session_title_changed event. If your agent keeps sessions in sync between Slack and your own UI, reflect the user's title change accordingly.

// agent_session_title_changed event payload
{
  "channel": "C123ABC456",
  "event_ts": "1783536983.783769",
  "previous_title": "Scuba diving research",
  "team_id": "T123ABC456",
  "thread_ts": "1782234671.392669",
  "title": "Bora Bora trip prep",
  "type": "agent_session_title_changed",
  "user": "U123ABC456"
}

Session visibility

Users subscribe to agent sessions by:

Initiating them, if they are listed as the initiator_user_id of a new session.
Participating in a thread that contains an agent session.

The sessions UX shows subscribed sessions in chronological order. Users can pin, rename, or archive sessions to manage their list.

All users in a channel can:

See the status and title of an agent session in that channel.
Change the title of an agent session in that channel.

Migrating from `assistant.threads.*`

The agents.sessions.setStatus and agents.sessions.rename methods replace assistant.threads.setStatus and assistant.threads.setTitle. Existing apps will keep working for now through a compatibility bridge, but migrating is recommended.

For step-by-step migration guidance, including the compatibility bridge details, the method replacement table, and how to implement the stop button, see Migrating to the Agent messaging experience.

Available methods​

Properties of an agent session​

Status values​

Session lifecycle​

Processing status​

Session timeouts​

Loading UX​

Customizing your agent's appearance​

Messaging interactions​

Stopping a session​

Renaming a session​

Session visibility​

Migrating from assistant.threads.*​