subagentic.ai RSS X YouTube GitHub
AI-generated illustration

How-Tos

How to open a Slack Code channel from an agent

Slack's docs show how to enable code channels and open a dedicated agent channel from an existing mention.

slackagents

Slack Code is how people work with an agent in dedicated channels, called code channels. When a user mentions your agent app, the app can create a code channel for that task. The channel looks and acts like a normal channel: users send messages, the agent responds, and everyone in the channel can follow along. Your app controls the title, status, context bar, and view tabs through agents.conversations.* and agents.sessions.*. One channel is created per task. Archive it when the session finishes. After that, the channel and its history remain viewable, searchable, and can be reopened.

The steps below are setup guidance from Slack's developer docs, not a launch note.

Enable code channels in the manifest

If the app already responds to mentions, enable code channels in the app manifest:

features:
     code_channels:
       enabled: true
       slash_command_url: https://example.com/slack/code-channel-commands  # optional

With features.code_channels.enabled set to true, the app receives app_mention events when users mention it. It can decide whether to create a code channel or reply in place, and it can call agents.conversations.*.

slash_command_url is optional. It tells Slack where to deliver invocations of slash commands the agent registers at runtime. The value must be https:// or http://, and at most 3000 characters. Socket Mode and hosted apps do not need this field.

Request code_channels:manage

agents.conversations.* requires the bot scope code_channels:manage. Those methods create the channel and set channel-level properties such as the context bar and external resources. agents.sessions.* requires only chat:write. Pass thread_ts for a thread session; omit it for a code channel.

Also request the scopes a conversational agent uses: app_mentions:read to receive mentions, chat:write to reply, and channels:history (or groups:history for private channels) to receive message events.

If the app already subscribes to message.channels or message.groups, those subscriptions also deliver messages from code channels. No extra subscription is required. To receive only code-channel messages, subscribe to message.session. It uses the same history scopes and the same message payloads. Subscribing to both does not duplicate delivery; each message is delivered at most once.

Create the channel from the mention

A mention such as @YourAgent please fix the flaky login test, in any channel, arrives as a normal app_mention event via the Events API or Socket Mode. Whether that becomes a code channel is the agent's call, made from the prompt and the context around it. Do not require the user to ask for a code channel or to know a command that creates one.

Open a channel when the work will take more than one message: back-and-forth, changing code, running builds or tests, opening a pull request, long output that would crowd the thread, or an explicit request for a session, task, or working space. Reply in place when one message is enough, when the request is about the surrounding conversation, or when people already in the thread should see the answer without leaving. If it is genuinely ambiguous, reply in place and offer to go deeper in a code channel. Slack's docs say this decision is better made by the model reading the request than by a keyword check in front of it.

If the mention is already inside a code channel, do not create another one. That can happen when a user started the channel via Slack's ephemeral prompt in a DM, or from Slack's own code channel UI. Call conversations.info and check that properties.record_channel.record_type is set to agent_channel. That block is written at creation and is on every code channel, even before the session has produced anything. Do not gate on properties.code_channel having content; a channel created moments ago has an empty {}. Read the origin link and session state from the same response, then continue there.

Otherwise call create with the origin channel and the triggering message timestamp:

POST /api/agents.conversations.create

{
     "name": "Fix flaky login test",
     "session_id": "ses_abc123",
     "origin_channel_id": "C0123456789",
     "origin_message_ts": "1717171717.123456"
}

Slack creates the channel, matches privacy, and invites your bot. Because you pass the origin link and omit is_private, Slack also sets privacy to match the origin channel, allows members of the origin channel to join, records the origin link as the channel's origin_link property, and names the channel from the origin message if you omit name. If you passed the origin channel and message timestamp, Slack unfurls a rich code channel card in the origin conversation. The card points to the new channel so users can see session details and click through.

session_id is an idempotency key. Retrying with the same session_id returns the existing channel rather than creating another.

A mention is the common pattern, not a requirement. The app can create a code channel from any message.

These guides do not document the create response body, so response field names are unknown from this material. Later examples address the channel with a channel_id such as C9876543210.

Every agents.conversations.* method other than create runs on an existing code channel. The caller must be the agent bot assigned to that channel, or a member of it. A call against a channel that is not a code channel fails with not_agent_channel. A call from a bot that is not the channel's agent fails with not_authorized. The bot is invited automatically at creation.

Set status, then archive

Working-session calls are made with the bot token against the code channel. On session start, set status to processing. agents.sessions.setStatus does not support a loading_message. While the session is processing, Slack shows the standard "Working…" loading UX. For a code channel, thread_ts is not supported on that method: the channel is one session, and separate agent sessions in its threads are not allowed.

POST /api/agents.sessions.setStatus

{
     "channel_id": "C9876543210",
     "status": "processing"
}

Keep processing while the agent is computing. Set active when a turn finishes with nothing outstanding. If you posted a question and need an answer before you can continue, set suspended rather than active. Channels are created with status active. Setting closed does not archive the channel; call archive instead.

If the focus changes, agents.sessions.rename updates both the channel name and the session title. Context-bar items go through agents.conversations.setProperties under code_channel.context_bar_items. You can pin up to five items, such as a repository, branch, PR link, CI status, or token usage. The array replaces the current set, so resend every item you want to keep. View tabs use agents.conversations.setView with type html, diff, block_kit, or canvas. That call is an upsert: the first call creates the backing file and channel tab; later calls replace the content and bump content_version.

Reply in the channel, not in a thread. Omit thread_ts unless the user threaded first or you are answering a specific earlier message. Respond even when you are not @-mentioned, unless the user is clearly talking to a human teammate. Subscribe to app_mention, message.session, or message.channels / message.groups so those messages arrive.

When the work is finished, post a final summary with chat.postMessage, then archive and pass that message's timestamp:

POST /api/agents.conversations.archive

{
     "channel_id": "C9876543210",
     "summary_message_ts": "1717182000.456789"
}

The channel is archived for all members. History remains readable. If you pass summary_message_ts, Slack records it as the channel's summary_message property before archiving. Archiving a channel that is already archived returns already_archived. Archived code channels stay in search and can be reopened. A common pattern is to post the wrap-up, offer an archive action such as a button, and call archive with the summary's ts once the user confirms.

If the user cancels the task, or Slack terminates a runaway session, the app receives agent_session_stopped and should cease all activity for that session immediately. Subscribe in the manifest:

event_subscriptions:
  bot_events:
    - agent_session_stopped

Stop processing for that channel or thread. Do not post further messages, and do not call agents.sessions.* or agents.conversations.* for that context. Slack updates the session status. If thread_ts is omitted, stop all work in the channel. If it is present, the stop applies to that thread.

What to do next

Read the code channel lifecycle from creation through archive, and keep the Slack Code guide open for the manifest, scopes, and method list. Then try the flow with the Coding Agent for Slack sample for Bolt for JavaScript or Bolt for Python. When mentioned with a task and a repo, those samples decide whether to answer in place or open a code channel.

Sources