32  Slack bot

Note

Workspace admins manage Slack bots from Settings. If Slack Integration is absent from Settings, confirm you are a workspace admin.

The Slack bot lets workspace members talk to Sophea agents from inside Slack. The bot uses Slack’s Socket Mode, so there is no public HTTPS endpoint, no request URL, and no signing secret to configure on the Slack side. You register a Slack app once on api.slack.com, install it to your workspace, then paste a Bot Token plus an App-Level Token into Nous.

This chapter walks through the full path: create the Slack app with the scopes Nous needs, enable Socket Mode and mint an App-Level Token, install the app, add the bot in Nous at /app/admin/bots/slack, route channels to agents, and confirm that mentions and direct messages reach Sophea.

32.1 Prerequisites

Before you start, confirm the following:

• You can sign in to the target Slack workspace as an admin, or you have an admin who can install your Slack app for you.
• You can sign in to Nous as a workspace admin.
• At least one agent is published in your workspace. See Agents if no agent is published yet.
• Optional but recommended: at least one document set is ready. See Document Sets.

Tip

Pick a private dev channel in Slack for the first test, for example #sophea-dev. Test mentions and direct messages there before you invite the bot to channels your users see.

32.2 Register a Slack app

Open https://api.slack.com/apps in a new tab and follow these steps.

1. Click Create New App, then choose From scratch.
2. Enter an app name, for example Sophea Bot, and select the target Slack workspace.
3. Click Create App. Slack drops you on the app’s settings page.

32.2.1 Configure bot scopes

Open OAuth & Permissions in the left sidebar and add the scopes Nous needs to read mentions, read channel history for context, and post replies.

Add the following bot token scopes:

• app_mentions:read: lets the bot see when users @mention it in a channel.
• channels:history: lets the bot read recent messages in public channels for thread context.
• groups:history: same as above for private channels the bot is invited to.
• im:history: lets the bot read direct messages to itself.
• im:read: lets the bot list direct-message conversations.
• im:write: lets the bot open a DM with a user.
• chat:write: lets the bot post replies.
• chat:write.public: lets the bot post in public channels it has not joined.
• users:read: lets the bot resolve user IDs to names for personalized replies.
• team:read: lets the bot read basic workspace info.
• files:read: optional, only add this if your channel routing needs to inspect attachments.

Add more scopes only if your channel routing needs them. Slack will warn users on reinstall whenever you change scopes.

32.2.2 Enable Socket Mode and mint an App-Level Token

Sophea’s Slack bot connects to Slack over a WebSocket, so you do not configure an Event Subscriptions request URL.

1. Open Socket Mode in the left sidebar and toggle Enable Socket Mode on.
2. When Slack prompts you for an App-Level Token, give the token a name (for example Sophea socket) and add the connections:write scope. This is the only scope this token needs.
3. Copy the generated token. It starts with xapp-. Slack will not show it again, so keep it in a scratch buffer.

Open Event Subscriptions in the left sidebar and toggle Enable Events on. Leave the request URL empty; events arrive over the Socket Mode connection. Under Subscribe to bot events, add at least:

• app_mention: the bot is mentioned in a channel.
• message.im: a user sends a direct message to the bot.
• message.channels: a message is posted in a public channel the bot is in. Add this only if you want the bot to react without an explicit mention.
• message.groups: same as above for private channels.

Save changes.

32.2.3 Install the app and capture the Bot Token

Open Install App in the left sidebar and click Install to Workspace. Approve the requested scopes on the Slack consent screen.

Slack returns you to the app page. Copy the Bot User OAuth Token from OAuth & Permissions. It starts with xoxb-. You now have the two required values, plus an optional third:

• Bot Token (xoxb-): from OAuth & Permissions.
• App-Level Token (xapp-): from Basic Information -> App-Level Tokens, the one you minted with connections:write.
• User Token (xoxp-, optional): only if you need user-impersonation features that the bot cannot perform with its bot token. Most workspaces leave this blank.

Warning

Both tokens are credentials. Treat them like passwords. Do not paste them into chat, do not commit them to git, and do not share them on screenshots when you record onboarding videos. Rotate any token from the Slack developer portal if you suspect it leaked.

32.3 Add the bot in Nous

Open the Integrations section in the left sidebar and click Slack Integration. This opens the Slack Integration page at /app/admin/bots/slack. The page lists every Slack bot already registered, with columns for Name, Status, Default Config, and Channel Count.

Slack Integration page showing the bot list

Click New Slack Bot in the top left area of the list to open the registration form.

New Slack Bot form with name and token fields

Fill in the form:

• Name This Slack Bot: a human-readable label, for example Admin Guide Demo Bot. This is only shown in the admin UI.
• Slack Bot Token: paste the xoxb- token from OAuth & Permissions.
• Slack App Token: paste the xapp- token you minted under Basic Information -> App-Level Tokens.
• Slack User Token (Optional): paste an xoxp- token only if you need enhanced private channel access.

Click Create. Nous verifies the tokens by calling Slack’s API and opening the Socket Mode connection. If a token is invalid or the workspace cannot reach Slack, the form returns an error and nothing is saved.

After creation, the bot appears in the list. Nous opens the Socket Mode connection in the background; once Slack delivers the first event, the Status column updates accordingly.

32.4 Route channels to agents

Open the bot from the list. The detail page shows the channel routing configuration.

Channel routing configuration for a Slack bot

Channel routing tells Nous which agent should answer when the bot is mentioned in a specific channel.

To add a route:

1. Click Add channel.
2. Paste the Slack channel ID, for example C0123456789. You find this in Slack by right-clicking the channel, then choosing View channel details and scrolling to the bottom.
3. Pick the agent from the Agent dropdown. Only agents already published in this workspace are listed.
4. Optionally restrict the channel to one or more document sets. The agent will only cite eligible documents from these sets. Ordinary shared-channel replies can search workspace-public content only; a private set does not make its documents visible there.
5. Click Save.

Repeat for every channel you want to bind. Channels without a route fall through to the bot’s default persona, if one is set. Otherwise the bot stays silent in unrouted channels.

Note

The bot must be invited to a private channel before it can receive events from that channel. In Slack, run /invite @Sophea Bot inside the channel. Public channels work as soon as the channel ID is added in Nous.

To remove a route, hover the row and click the trash icon. To change the agent on a route, click the agent name and pick a different one. Changes apply on the next mention.

32.5 Test and troubleshoot

Run these checks in your dev channel, in order, before you announce the bot to users.

32.5.1 Direct message check

1. In Slack, click the bot’s name in the sidebar Apps section to open a DM.
2. Send a short prompt, for example hello, are you up?.
3. The bot replies within a few seconds. If it does not, the most likely cause is a missing im:history or chat:write scope. Reinstall the app after adding scopes.

32.5.2 Channel mention check

1. Invite the bot to your dev channel: /invite @Sophea Bot.
2. Mention it: @Sophea Bot what is in our onboarding doc set?.
3. The bot replies in the same thread. The reply cites the document set bound to this channel.

If the bot stays silent on a mention:

• Confirm the channel ID is registered under channel routing.
• Confirm an agent is selected for that channel, or a default persona is set on the bot.
• Check the Status column on the Slack Integration page and confirm it updated after your mention. If it did not update, Slack could not deliver the event over the Socket Mode connection. Open the bot, recheck that the App Token (xapp-) is still valid in Slack, and re-save the bot to reopen the connection.

32.5.3 Permissions check

Slack response visibility depends on how the reply is delivered:

• A bot direct message or an ephemeral reply can use the mapped Nous user’s private-document permissions.
• An ordinary reply posted into a shared channel deliberately searches as an anonymous user and can use workspace-public documents only, even when the sender personally has access to private content.

If a shared-channel reply has no citations, confirm the routed document sets contain workspace-public content. To test a member’s private access, use a direct message or an ephemeral response and compare it with the same query in the member’s normal Nous chat at /app.

32.5.4 Common failures

• invalid_auth on create: the Bot Token (xoxb-) was copied incorrectly or was rotated in Slack. Recopy from OAuth & Permissions -> Bot User OAuth Token.
• invalid app token on create: the App-Level Token (xapp-) is missing the connections:write scope, was deleted, or was pasted into the wrong field. Recreate it under Basic Information -> App-Level Tokens and paste the new value.
• Bot ignores mentions in a public channel it just joined: confirm app_mentions:read and chat:write.public scopes, then reinstall the app.
• Bot replies but with no citations: the channel route has no document set selected, or the bound agent has Use Knowledge turned off. Open the agent in /app/agents and confirm. See Agents.
• Slack Integration is missing from Settings: confirm you are a workspace admin.

Once the dev channel passes all three checks, invite the bot to its target user channels and announce it.