--- title: Set up Slack canonical: "https://agentbarn.dev/guides/platforms/slack" pubDate: "2026-08-29T00:00:00.000Z" updatedDate: "2026-09-14T04:31:13.000Z" author: Agent Barn description: "Connect an Agent to Slack, configure access policies and a default delivery target, and understand replies and scheduled results." tags: [Platforms, How-to, "Slack administrators, Agent operators, Agent creators, and Organization administrators", scheduled results, default delivery target, initiated messages, Slack, Socket Mode, access policy, mentions, progress messages, verbose mode, Announce steps, Hermes] categories: [Guides, Platforms] --- Connect Slack to an existing Agent by creating a Slack Communication Connection. You create the Slack app from a manifest, generate its tokens, and paste them into the Connection. Slack works with both Hermes and OpenClaw. Agent Barn owns the Slack Socket Mode session through the Communications Gateway, and the Agent Runtime never receives Slack credentials. ## Overview Slack is not selected while creating the Agent. The Agent is created headless, and Slack is added afterward as a Connection. - An Agent can have zero or many Communication Connections. - The same Agent can have multiple Slack Connections, such as one per workspace. - Slack works with both Hermes and OpenClaw, because provider support comes from the Slack Platform Plugin. - The Communications Gateway holds the Socket Mode session, so no public inbound Slack endpoint is required. - The Agent Runtime never receives the Slack bot or app-level token. A Slack Connection requires: - A Slack application with Socket Mode enabled - The bot scopes and event subscriptions supplied by the manifest - An app-level token beginning with `xapp-` - A bot token beginning with `xoxb-` - The application installed in the intended Slack workspace See [Communication Connections](/guides/agents/communication-connections) for the shared Connection lifecycle, and [Compare platform compatibility](/guides/platforms/compatibility) for how Slack sits beside the other Platforms. ## Slack connection model Slack events reach the Agent through the Communications Gateway rather than directly: 1. Slack events 2. Slack Platform Plugin 3. Communications Gateway 4. Communication Delivery 5. Hermes or OpenClaw Replies return through the same path, and the Gateway sends them with the Connection's own credentials. Slack's [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode/) delivers events over a WebSocket instead of posting them to a public Request URL. **Important** Do not configure a Slack Events API Request URL, and do not provide a signing secret. Slack uses Socket Mode and the `xapp-` app-level token. ### Token types | Credential | Prefix | Purpose | Required scope | | --- | --- | --- | --- | | App-level token | `xapp-` | Opens the Socket Mode connection held by the Communications Gateway | `connections:write` | | Bot token | `xoxb-` | Authenticates Slack Web API calls as the bot | Bot scopes granted at installation | Slack documents these as separate [token types](https://docs.slack.dev/authentication/tokens/). Both belong to the Communication Connection, and both are required. Do not use a user token beginning with `xoxp-`, a signing secret, or an incoming webhook URL. ## Before you begin You need: - An existing Agent - Permission to update that Agent and manage its Connection credentials - Permission to create and install a Slack app in the target workspace - A Slack bot token beginning with `xoxb-` - A Slack app-level token beginning with `xapp-` Slack uses Socket Mode, so the deployment does not require a public inbound Slack webhook. Your Slack workspace may require administrator approval before an application can be created or installed. Complete that approval first. **Security** Slack tokens authorize access to Slack workspace data and operations. Never commit them to source control, paste them into a Template or Skill, or send them through a Slack message. Enter them only into the Connection credential fields. ## Create the Slack app from a manifest Create the Slack application first, using the manifest that the Connection form provides. 1. Open [Slack app management](https://api.slack.com/apps). 2. Select **New App**. 3. Select **From Manifest**. 4. In Agent Barn, use **Copy Slack manifest** on the Connection form. 5. Paste the copied manifest into Slack. 6. Choose the intended workspace. 7. Select **Next**. 8. Review the configuration and select **Create**. The supplied manifest configures the Slack app, Socket Mode, bot events, and requested scopes. It does not create the app-level token; that is a separate manual step. For an application that already exists, open **Features β†’ App Manifest** instead and merge the copied manifest into the current one. **Note** When an existing application's scopes or permission-dependent events change, reinstall it so the bot token receives the new grants. Slack documents this in its [app lifecycle guidance](https://docs.slack.dev/app-management/distribution/). ## Create the app-level token The app-level token opens the Socket Mode connection. 1. Open **Basic Information** for the Slack app. 2. Find **App-Level Tokens**. 3. Create an app-level token with the `connections:write` scope. 4. Copy the resulting `xapp-` token. 5. Confirm that Socket Mode is enabled. **Important** Slack manifests cannot create app-level tokens, so this step must be completed manually. A bot token with bot scopes cannot replace it. Slack's [`connections:write` scope](https://docs.slack.dev/reference/scopes/connections.write/) allows an app-level token to open the Socket Mode connection. Copy the token when it is generated; Slack does not show it again. ## Install the app and copy the bot token 1. Open **OAuth & Permissions**. 2. Install the Slack app into the selected workspace. 3. Copy the **Bot User OAuth Token** from **OAuth Tokens for Your Workspace**. 4. Confirm that the value begins with `xoxb-`. 5. Reinstall the app after changing its bot scopes. **Bot token availability** Before install No bot token is issued yet After install A Bot User OAuth Token beginning with `xoxb-` is available Private channels and conversations require the bot to be invited before it can access them. In the private channel, run `/invite @bot-name`. ## Create the Slack Connection With both tokens in hand, create the Connection on the Agent. 1. Open the existing Agent. 2. Open its **Communication Connections** section. 3. Choose Slack. 4. Enter a Connection display name. 5. Paste the `xoxb-` bot token into **Bot token**. 6. Paste the `xapp-` app-level token into **App-level token**. 7. Configure the Connection policies. 8. Create and enable the Connection. Use a display name that identifies the workspace or purpose, such as `Slack: Support workspace`. **Security** These credentials belong exclusively to the Communication Connection. They are encrypted at rest, are not returned after storage, and are never materialized into Hermes or OpenClaw. An active Slack bot token must not be reused by another Communication Connection where global credential uniqueness applies: ``` This Slack bot token is already in use by another Communication Connection. ``` ## Configure the Connection settings The Slack Platform Plugin supplies these settings on the Connection form. | Setting | Behavior | Underlying setting | | --- | --- | --- | | Default delivery target | One non-retired Connection per Agent may hold the default for scheduled work without a conversation origin. Disabling it retains the slot but prevents default delivery. | `default_delivery_target` | | Channel access | open: respond in any channel where the bot is present; allowlist: respond only in the selected allowed channels | `group_policy` | | Allowed channels | Slack channel IDs, used when Channel access is allowlist | `channel_ids` | | Direct messages | off: ignore direct messages; open: accept from any Slack user; allowlist: accept only from selected users | `dm_policy` | | Allowed DM senders | Slack user IDs, used when Direct messages is allowlist | `dm_user_ids` | | Thread mention policy | every\_message: every channel message, including every thread reply, must mention the bot; start\_only: a mention starts the interaction, then unmentioned replies are accepted in threads this Agent and Connection already own | `thread_mention_policy` | | Announce steps | Exposed in the schema but not used by the current delivery path to control progress; use Agent-level Hermes verbosity | `verbose_mode` | Start narrow. A good first configuration is one allowed channel, direct messages off, and `every_message` thread mentions. **Example starting policy** Channel access `allowlist` with one test channel Direct messages `off` Thread mention policy `every_message` Widen the policy after the first successful exchange. See [Configure channel access](/guides/agents/channel-access) for policy guidance. **Warning** An allowlist never installs or invites the bot. Slack channel membership and installation requirements still apply, and `open` only permits messages from channels where the bot is already present. ## Use workspace directory discovery Slack supports credential-backed directory discovery for channels and active workspace users, so you can pick from the workspace instead of hunting for IDs. - Draft Slack credentials can be used to load the workspace before the Connection is created. - A saved Connection can browse its own workspace directory. - Channel and user suggestions can populate the allowlists. - Only Slack provider IDs are persisted. - Manual ID entry remains available. A directory lookup failure does not expose provider response text or stored credentials, and it does not block you from configuring an allowlist by hand. A private channel appears only after the bot has been invited to it. Invite the bot in Slack, then load the directory again. ## Send a separate Slack message An Agent can send a separate Slack message when you request it during an active conversation. The message stays on the Communication Connection that received your request. You can name a channel or person in that workspace; it cannot switch to another Connection or workspace. Current channel and direct-message policies still apply. Use provider IDs when names are ambiguous. Group direct messages are not supported for initiated delivery. A queue receipt means Agent Barn accepted the message for delivery. It does not prove that Slack received it. Use [Communication diagnostics](/guides/observe-and-govern/communication-diagnostics#recent-failures) to inspect delivery failures and recovery. ## Configure the default delivery target The default gives scheduled work created outside a conversation a destination. It does not redirect jobs that already have a recorded conversation origin. 1. Open the Agent's Communication Connections and edit the intended Slack Connection. 2. Under **Default delivery target**, enable **Send scheduled results through this Connection**. 3. Choose **Channel or group** or **Person** as the destination type, then select or enter the **Default channel or recipient**. For Slack, group direct messages are unsupported even though the shared field label includes β€œgroup.” 4. Save the Connection and keep it enabled. The bot must have access to the destination, and the Connection's channel or direct-message policy must permit it. Only one non-retired Connection per Agent may hold a default target. To move the default, clear it from the old Connection before setting the new one. Disabling a Connection does not release its default slot, and a disabled Connection cannot deliver through that default. Connection settings reconcile independently of the running Agent; deploying new runtime support still requires a compatible runtime rollout. ## Where scheduled results go Hermes jobs created from a conversation retain that Connection, channel, and thread. Jobs created at startup, outside a conversation, use the configured default. Changing the default does not move a job with a recorded origin. A Hermes job can target a different thread or the channel root within its originating channel. It cannot change to another channel through this setting. An unsupported destination is refused rather than rerouted. To schedule work for a different channel, create the job from that channel. OpenClaw completion capture is supported, but its pinned cron hook can report a delivery-channel label without a usable creating-conversation origin. Those unmappable completions are refused. Only completions with no recorded origin use the default; do not treat a default target as a workaround for an unknown origin. Scheduled work sends its final response through Agent Barn. It does not call the interactive message tool. See [the runtime guide](/guides/runtime-and-deployment#section-5) for routing details, silence markers, and delivery recovery. ## Verify the Connection Confirm the Connection is enabled and shows no provider error, then run these tests from a controlled channel. | Test | Expected result | | --- | --- | | Mention the Agent in an allowed channel | The Agent responds | | Send an unmentioned message in an allowed channel | The Agent does not respond | | Mention the Agent in a channel outside the allowlist | The Agent does not respond | | Send a direct message while Direct messages is `off` | The Agent does not respond | | Send a direct message as an allowed user while Direct messages is `allowlist` | The Agent responds | | Reply in a thread without a mention under `every_message` | The Agent does not respond | | Reply in an Agent-owned thread without a mention under `start_only` | The Agent responds | Then confirm the exchange in Agent Barn: 1. Open the Agent. 2. Open **Conversations**. 3. Select this Slack Connection. 4. Confirm the inbound message and outbound response appear under it. See [Verify your Agent](/guides/get-started/verify-agent) for the full layered verification. ## Mention behavior Mention requirements are a Connection policy, not a fixed Slack rule. - New channel interactions require a direct bot mention. - Direct messages do not require a mention, but remain governed by the direct-message policy. - Thread replies follow the Connection's `thread_mention_policy`. - Under `start_only`, unmentioned replies are accepted only in a persisted thread already owned by that Agent and Connection. ``` @release-reviewer Review this deployment. ``` The Slack Platform Plugin also ignores bot events, edit events, and duplicate `app_mention` deliveries, so the Agent does not answer itself or reply twice to the same mention. Use `every_message` for busy shared channels, and `start_only` where a thread is a deliberate working session with the Agent. ## Processing feedback Slack users may see lightweight feedback while a request is handled: | Signal | Meaning | | --- | --- | | πŸ‘€ | The inbound message was accepted | | Processing status | The Runtime is working on the request | | βœ… | The outbound response was delivered successfully | | ❌ | A terminal Runtime or provider failure occurred | This feedback is best-effort. It does not replace the durable delivery state shown in the Connection's diagnostics. ## Change the Connection later Slack settings and credentials can be changed at any time without touching the Agent. - Connection updates increment the Connection revision. - The Communications Gateway reconciles the Slack session independently. - Updating the Connection does not rebuild or restart the Agent Runtime. Use the Connection's diagnostics for provider health, reconnects, rejected messages, retries, and delivery failures. Check Runtime health separately when Slack accepts a message but the Agent produces no reply; that is a Runtime problem, not a provider problem. **Note** Rotating a Slack token in Slack can immediately break the Connection's session. Prepare the replacement, then update the Connection credentials; no Agent restart is required. ## Slack app manifest The Connection form exposes the current manifest through **Copy Slack manifest**. Copy it from there rather than transcribing it, so the app always matches the installed Slack Platform Plugin. The manifest configures: - The Slack app display information and bot user - Socket Mode - Bot event subscriptions - Requested bot scopes It does not create the app-level token, and it does not install the app. **Note** The manifest's scope list reflects the full set of Slack capabilities the plugin can use. It is not the minimum set every deployment consumes, so review it against your workspace's policy before requesting administrator approval. The manifest requests only bot scopes; no Slack user OAuth token is needed. After adding or changing bot scopes, reinstall the application so the bot token receives the new grants. ## Credential management Both Slack tokens belong to the Communication Connection. | Credential | Where to manage it | Effect of rotation | | --- | --- | --- | | App-level token | Slack app Basic Information, then the Connection credentials | Affects the Socket Mode session | | Bot token | Slack app OAuth & Permissions, then the Connection credentials | Affects Slack API identity and operations | Replacing a token requires Agent secret-management permission. Enter the new value on the Connection; the Gateway reconciles the session on the next revision. **Important** Slack communication and Slack tool access are different things. Communication Connection credentials provide message transport. A Slack tool Integration credential lets an Agent Skill call Slack APIs as a tool. They have separate ownership and security lifecycles, and creating a Slack Communication Connection does not grant general Slack tool access. ### Retiring a Slack Connection Retiring the Connection removes it from active use and releases its provider credential identity where uniqueness applies, while preserving its Conversation history. It does not uninstall the application from Slack. Afterward: 1. Open the Slack application. 2. Revoke tokens or uninstall the application when it is no longer needed. 3. Remove the bot from any private channels. 4. Review the application against your Slack administration policy. ## Troubleshooting Work through these checks first: - The `xapp-` token has `connections:write` - The `xoxb-` token comes from the intended workspace - The app was reinstalled after scope changes - Socket Mode is enabled - The bot was invited to the relevant private channel - The channel or sender passes the configured allowlist - The message satisfies the configured mention policy - The Connection is enabled and healthy ### The app-level token is rejected Check that it begins with `xapp-`, belongs to the intended Slack application, carries `connections:write`, and has not been revoked. Confirm Socket Mode is enabled, then generate a new app-level token if necessary. ### The bot token is rejected Check that it begins with `xoxb-`, that the application is installed in the intended workspace, and that it has not been revoked. Copy the **Bot User OAuth Token**, not a user token. ### The bot token is already in use Where global credential uniqueness applies, another Communication Connection already holds this token. Create a separate Slack application for the new Connection, or retire the Connection that holds the existing token. ### Slack requires administrator approval Submit the application through the workspace's normal administration process. The administrator should review the requested bot scopes, event subscriptions, Socket Mode, interactivity, and the intended channels and users. ### A channel does not appear in the directory Confirm that the bot token is valid, that the application has the channel-reading scopes, that it was reinstalled after those scopes were added, and that the channel is not archived. For a private channel, run `/invite @bot-name` in Slack, then load the directory again. Manual channel ID entry remains available. ### Scopes were added but behavior did not change Reinstall the Slack application. Updating a manifest changes the application definition, but an already-issued bot token keeps its original grants until the app is installed again. ### The Connection shows a provider error Review the Connection's health and diagnostics. Check whether a token was revoked, the application was uninstalled, Socket Mode was disabled, or workspace authentication requirements changed. Do not restart the Agent for a provider-session problem. Correct the Slack side or the Connection credentials, and the Gateway reconciles the session. ### Slack accepts the message but no reply arrives If the inbound message appears in Conversations, admission worked and the problem is downstream. Review [Agent health and logs](/guides/agents/health-and-logs) for the Runtime, then review the Connection's delivery diagnostics for the outbound reply. ### The Agent responds in direct messages but not channels Check the channel access policy, the allowed channel list, bot membership for private channels, whether the app was reinstalled after scope changes, and whether the message satisfies the configured thread mention policy. ## Next steps After the Slack Connection is working: - [Review the Connection lifecycle](/guides/agents/communication-connections) - [Configure channel access](/guides/agents/channel-access) - [Verify your Agent](/guides/get-started/verify-agent) - [Review Agent health and logs](/guides/agents/health-and-logs), separately from Connection health - [Compare platform compatibility](/guides/platforms/compatibility) before adding another Connection - [Set up Telegram](/guides/platforms/telegram) ## Current limitation: Announce steps The Slack Connection schema exposes an **Announce steps** field, but the current delivery path does not use that Connection-level setting to control progress. Hermes progress is controlled by the Agent's verbosity setting. Changing the Slack field alone does not enable or suppress progress. OpenClaw does not support the current progress relay.