Migrating to the Agent messaging experience

In the Agent messaging experience, agent conversations happen in the classic Messages tab of the app, with threads shown in a timeline above the composer. Apps that already use the Assistant messaging experience can continue to use it for now, but assistant_view will eventually be deprecated, and we'll ask existing apps to migrate.

To move an existing app from the Assistant messaging experience to the Agent messaging experience, work through the following steps.

1. Switch the manifest from assistant_view to agent_view.

   This change enables the Agent messaging experience for all users of your app. See the app manifest reference for the field definitions. To configure in the app settings, navigate to the Agent tab in the left nav, then select the button to update the app. When switching to agent_view, the nested assistant_description switches to agent_description.

2. Detect when a user opens a DM with the app_home_opened event.

   Subscribe to the app_home_opened event to be notified when a user has opened a DM with your app. Specifically, check the value of the tab property of the event to verify when its value is "messages".

   JavaScript example:

   if (event.tab === 'messages')

   Python example:

   if event.get("tab") == "messages"

   This replaces the assistant_thread_started event. Without the assistant_thread_started events, messages received in the DM channel will not have a root message with subtype = "assistant_app_thread"; rather, the root message will appear from the user.

3. Revisit how you set suggested prompts.

   Suggested prompts now live at the top of the Messages tab instead of within a thread. If your app set prompts contextually for each thread, review that logic.

4. Move from assistant.threads.* methods to agents.sessions.*.

   The agents.sessions.setStatus and agents.sessions.rename methods replace assistant.threads.setStatus and assistant.threads.setTitle. Your existing calls keep working through a compatibility bridge, so this step is not yet required to switch experiences, but we recommend migrating as part of this move. See Migrating from assistant.threads.* methods below.

5. Implement the stop button.

   Slack shows a native stop button while a session is in processing if your app subscribes to the agent_session_stopped event. Subscribe to it so users can stop your agent, and transition the session out of processing when you receive the event. See how to implement stop below.

Switching to agent_view cannot be reversed

Once you change your app's manifest from assistant_view to agent_view, you can't revert to the Assistant messaging experience. After the change, users will need to hard refresh Slack to see the Agent messaging experience. If your app is already distributed, this change will require going through Marketplace review.

Migrating from assistant.threads.* methods

The agents.sessions.setStatus and agents.sessions.rename methods replace assistant.threads.setStatus and assistant.threads.setTitle. The sessions API works with channels and DMs and supports richer lifecycle states. For the full lifecycle and concepts, see Agent sessions.

Compatibility bridge

Existing apps using the legacy APIs will continue to work. Slack bridges calls to the sessions system automatically:

• assistant.threads.setStatus with a non-empty status string sets the session to processing. An empty status string sets the session to active.
• assistant.threads.setTitle applies the provided title to the thread's agent session.

For apps using the streaming API methods (chat.startStream and chat.stopStream), the bridge ensures your app participates in the sessions UX without code changes by automatically creating sessions. We plan to deprecate the assistant.threads.setStatus and assistant.threads.setTitle methods in favor of the agents.sessions.setStatus method, and we recommend migrating as part of this move.

Replace setStatus and setTitle

Replace calls to the legacy API methods with the sessions methods:

Before	After
assistant.threads.setStatus with non-empty status	agents.sessions.setStatus with status: "processing"
assistant.threads.setStatus with empty status	agents.sessions.setStatus with status: "active"
assistant.threads.setTitle	agents.sessions.rename with title: "..."

Status and title are managed by separate methods. You can also use the suspended and closed statuses for richer lifecycle management.

// Before
POST /api/assistant.threads.setStatus
{ "channel_id": "C123", "thread_ts": "1234123.232342", "status": "is typing..." }

POST /api/assistant.threads.setTitle
{ "channel_id": "C123", "thread_ts": "1234123.232342", "title": "Deep sea diving research" }

// After
POST /api/agents.sessions.setStatus
{
  "channel_id": "C123",
  "thread_ts": "1234123.232342",
  "status": "processing",
  "title": "Deep sea diving research"
}

POST /api/agents.sessions.rename
{
  "channel_id": "C123",
  "thread_ts": "1234123.232342",
  "title": "Deep sea diving research"
}

You must explicitly end the processing state

Unlike assistant.threads.setStatus, the loading UX no longer disappears automatically when your app posts a message to the thread. We expect apps to call agents.sessions.setStatus with status: "active" when they finish their work; otherwise the session stays in processing until it times out after one hour.

Implement stop

The native stop button only appears if your app subscribes to the agent_session_stopped event; while your app is not subscribed, the user sees a non-interactive loading indicator instead. Subscribe to the event and transition the session out of processing when you receive it. See Stopping a session for details.