Connect a Bot to Slack

Version scope: current-source guide. These steps include UI updates absent from npm v1.1.0; older test packages and screenshots are historical verification records. See Connections and optional tools for release and component boundaries.

Connect a PersonaBot to Slack: configure an application, connect it locally and bind it to the Bot. After binding, @mentions of the app in channels it belongs to reach this Bot's Inbox, and the Bot replies in the same Slack thread. You don't authorize each channel.

#Understand the three settings

Where the Bot can speak is decided by Slack: the channels the app was invited to and the scopes you installed. Binding an app does not mirror messages into a local DM, and an app belongs to one Bot.

#1. Prepare your environment

You need a Slack workspace that allows application installation, permission to create an app (or an administrator's help), and a public test channel. Create a PersonaBot in BotHarness and confirm that it can answer a local DM before testing Slack.

Use a BotHarness product with its qualified IM Provider included. Do not separately install an arbitrary dsh-im version or start a second receiver for the same app.

Historical qualification (#868; the public product is now deepseekbot v1.1.0): The verified product is 0.0.0-test.868, with Provider 4.32.0-botharness.3 and DSH 0.2.0-rc.1. If you need to build it, follow the product installation notes at that revision. Keep the launcher's login URL private and reuse the same Profile to retain settings.

Screenshots show actual controls and the dedicated “BotHarness Slack QA” app in DoodleBear. Setup and configured states are labelled separately. Configured runtime captures come from the accepted #868 product; shared-Channel captures come from #845. No tokens appear in the images. Open an image to see its original size.

#2. Create the Slack application

1. In BotHarness, open Settings → IM bots → Slack → Start setup (开始接入).
2. Select Copy Manifest (复制 Manifest), then Open Slack creation page. At Your Apps, select Create New App → From a manifest. Choose your workspace, paste the copied configuration, review the app name, permissions and events, and create it. Your organization may require administrator approval.
3. Keep the local setup form open; the two token fields will be filled after the app is installed.

The empty form shows where to start and where credentials belong; it does not prove a connection.

Select From a manifest. This capture stops before creation; reuse your own workspace and application name.

The manifest is a starting configuration, not a credential. Compare your app with the settings below before connecting. Slack's manifest documentation explains how the configuration is applied.

#Socket Mode and App Token

Open the app's Socket Mode page and enable it. BotHarness receives events through this outbound WebSocket connection; you do not need a public Request URL or an incoming Webhook.

Under Basic Information → App-Level Tokens, generate an App Token with connections:write. Keep the xapp-… value private; it belongs in the local App Token field, not Bot Token. See Slack's Socket Mode guide.

The existing QA app has Socket Mode enabled. This page does not display its App Token.

#Bot permissions and events

Under OAuth & Permissions → Bot Token Scopes, check permissions by purpose:

The screenshots show the already approved QA app, including optional file permissions. Request only the access your use case needs. Adding scopes requires workspace installation or reinstallation before the granted token can use them.

These are Bot permissions. Signing in as a Human, or granting User Token scopes, does not replace the application bot's authorization.

Under Event Subscriptions, enable events and add app_mention to Subscribe to bot events. Add message.channels if you want ordinary public-channel text or topic following. Save the subscription. Socket Mode removes the Request URL requirement.

Permissions allow access; subscriptions determine which live events Slack sends. BotHarness still filters them through the authorized channel and intake policy. See the official app_mention and message.channels references.

#3. Install and connect locally

1. In the Slack app console, use Install App → Install to Workspace (or OAuth & Permissions → Install/Reinstall to your workspace). Review the requested scopes and complete any administrator approval.
2. Obtain the Bot User OAuth Token (xoxb-…) under OAuth & Permissions. This is the Bot Token, used for the installed bot's API operations. It is different from the xapp-… App Token used for Socket Mode.
3. Return to the local setup form, enter each token in its matching field and select Verify and connect (验证并连接). Credentials stay in the local credentials service; do not paste them into chat, Memory or Git.
4. Confirm the app is online in Settings → IM bots → Slack. Invite the application bot to your public test channel through Slack's channel integrations or /invite @YourAppName.

The connected account is the actual #868 installed-product result, not a filled-form mock. See Slack's installation documentation.

#4. Bind the app to the PersonaBot

Open the PersonaBot's DM and, in the Channel sidebar on the right, expand External identities. Select + Bind app, choose the connected Slack app and confirm. Once the row shows Ready, @mentions of the app in channels it belongs to go straight to this Bot's Inbox, and the Bot replies in the same thread. See External identities.

Screenshots in this section show the earlier Profile layout; binding now lives in the sidebar's External identities entry.

Each channel appears in the app's conversation list after its first admitted message. New conversations decides whether it is admitted automatically (the default) or waits for you under Waiting. Use Mute, Rules and Block on a row to quiet, tune or refuse that channel; Allow again lifts a block without backfilling missed messages.

#5. Verify a mention and same-thread reply

In a Slack channel the app belongs to, send an actual @mention selected from Slack's mention picker, for example:

@YourAppName Please reply “SLACK-OK” in this Slack thread using bridge_reply. Do not send a local DM.

Open Bot Inbox in the PersonaBot's sidebar (or the Activity Center), locate the new source and open its details. Check the Slack channel, original sender, receiving identity and message content. “Handled” means the Bot processed the source; it does not replace checking the actual external reply.

This #868 source belongs to a real Human follow-up on a previously sent Slack report. Its local route is Inbox-only, so no local DM message is created.

The model replied BH868-PRODUCT-OK and BH868-RESTART-OK in the original Slack thread. Use your own test phrase to verify your installation; these captures are evidence from the named QA app.

Also send one plain, unmentioned message. With mentions-only intake and no explicit topic-follow policy, it should not enter this Bot's Inbox. Replying once does not automatically make the Bot follow every message in the thread.

#6. Optional: sync a channel into a local Channel

By default Slack messages reach only the Bot Inbox and do not occupy local DM history. Adding a new sync is being redesigned: External connectors will take a conversation from any connected app and stream it into a Channel. Existing syncs keep working. Each member Bot of a shared Channel keeps its own Attention/wake policy.

This #845 capture shows the earlier connector dialog. Edit, pause or remove existing syncs under External connectors.

Pausing a sync stops new intake while keeping its configuration and history. Removing it does not delete earlier messages. Disabling an external identity and pausing a sync are separate actions.

#Ordinary messages, harvest and topic following

Start with @mentions. To collect ordinary text, first enable channels:history and message.channels, install the changed permissions, then send a plain test message in the channel and refresh. BotHarness requires observed ordinary-message delivery before offering all-message intake or topic following.

Open Rules on the channel's row and choose custom all messages intake only for the intended channel. Select count/time harvest (for example, 5 messages or 30 seconds), or safely queued immediate wake. For shared Channels, each member Bot chooses when to process those messages through its own Attention settings. Intake, waking and whether to reply are separate decisions.

A Bot may explicitly follow or leave one native Slack topic. Human can inspect or override this in Topic following. Unmentioned replies in a followed topic can enter; unrelated topics keep their own rules. A Bot can also request bounded channel, nearby or thread context with continuation, without importing the history as new Inbox messages.

Bot settings → Slack defaults controls the default intake, harvest and identity-enabled behavior. A channel's Rules can inherit these values or explicitly override them. Global changes apply to subsequent events for inheriting configurations; they do not create accounts, admit channels or replay old history.

Slack can address channels directly, so a saved send target is never required. The External connectors → Save a send target (advanced) fallback stays for apps that can't.

#Troubleshooting

The historical qualification below covers public-channel mentions, ordinary text, bounded context, native topic following, explicit shared-Channel routing, mentioned-file processing and explicit reports. Private channels/Slack DMs, unmentioned file-share intake, edits/deletions, workspace-wide search, automatic gap backfill and a scheduled morning-report service are outside this qualification. Slack read indicators are not BotHarness receipt evidence. For provider-specific boundaries and future adapters, see the IM integration guide.

The current-source Slack DM path was qualified separately in #1125; the #868 public-channel evidence above does not prove DMs. See External identities for binding.