Slack Bot

Ask ZenSearch questions directly from Slack. The bot responds in-thread with cited answers, source references, and follow-up suggestions.

info

The Slack bot is separate from the Slack data connector. The connector indexes your Slack messages for search. The bot lets you query ZenSearch from within Slack.

Using the Bot

Mention in a Channel

Mention the bot in any channel it's been added to:

@ZenSearch how do I configure SSO?

The bot responds in a thread with:

• A cited answer based on your indexed knowledge
• Source references (up to 5)
• Follow-up suggestion buttons

Direct Message

Send a DM to the bot — no @ mention needed:

What data sources are supported?

Slash Command

Use the slash command for a private response visible only to you:

/zensearch what are the API rate limits?

note

Slash command responses are ephemeral (private). Follow-up suggestions are not available in ephemeral mode — use @ mentions or DMs for interactive conversations.

Conversations

The bot maintains conversation context within a Slack thread. Follow-up questions in the same thread use previous context for better answers.

• Thread scope: Each Slack thread maps to a ZenSearch conversation
• Session duration: 24 hours of inactivity starts a new conversation
• Cross-platform: Conversations started in Slack can be continued in the web app

Follow-up Suggestions

After each answer, the bot may suggest related questions as clickable buttons. Clicking a suggestion posts a new message in the same thread.

Agent Approvals

When an agent action requires approval (e.g., executing a tool with side effects), the bot posts an approval card with Approve and Deny buttons.

• Only team Admins and Owners can approve or deny
• The card updates to show who took action and the decision
• Approved actions resume automatically; denied actions stop the agent

Setup (Admin)

Prerequisites

• A Slack workspace where you have admin permissions
• A ZenSearch team with data sources configured

1. Create a Slack App

1. Go to api.slack.com/apps and click Create New App > From scratch
2. Name it (e.g., "ZenSearch") and select your workspace

Bot Token Scopes

Under OAuth & Permissions > Scopes > Bot Token Scopes, add:

Scope	Purpose
app_mentions:read	Respond to @mentions
chat:write	Post messages
channels:history	Read channel messages (for thread follow-ups)
groups:history	Read private channel messages
im:history	Read DM messages
mpim:history	Read group DM messages
users:read	Read user profiles
users:read.email	Read user emails (for automatic identity matching)
commands	Handle slash commands

OAuth Redirect URL

Under OAuth & Permissions > Redirect URLs, add:

https://YOUR_API_DOMAIN/api/v1/integrations/slack/auth/callback

Event Subscriptions

Under Event Subscriptions, enable events and set the request URL to:

https://YOUR_API_DOMAIN/api/v1/surfaces/slack/events

Subscribe to these bot events:

• app_mention — Respond to @mentions
• message.im — Respond to DMs
• message.channels — Thread follow-ups in channels
• message.groups — Thread follow-ups in private channels

Interactivity

Under Interactivity & Shortcuts, enable and set the request URL to:

https://YOUR_API_DOMAIN/api/v1/surfaces/slack/interactions

Slash Commands (Optional)

Under Slash Commands, create a /zensearch command pointing to:

https://YOUR_API_DOMAIN/api/v1/surfaces/slack/commands

2. Configure ZenSearch

Set these environment variables on the core-api service:

Variable	Description
SLACK_SIGNING_SECRET	From your Slack app's Basic Information page
SLACK_CLIENT_ID	From Basic Information > App Credentials
SLACK_CLIENT_SECRET	From Basic Information > App Credentials
SLACK_BOT_ENABLED	Set to true to enable the bot
SLACK_OAUTH_REDIRECT_URL	https://YOUR_API_DOMAIN/api/v1/integrations/slack/auth/callback

Restart the core-api service after setting these values.

3. Connect the Workspace

1. Go to Settings > Integrations > Slack in the ZenSearch web app
2. Click Add to Slack
3. Authorize the app in the Slack popup
4. The workspace appears as connected

4. User Identity Linking

ZenSearch automatically matches Slack users to ZenSearch accounts by email on first message (using the users:read.email scope). No manual setup is needed if user emails match.

If automatic matching fails, users can be linked manually via the identity links API:

curl -X POST https://YOUR_API_DOMAIN/api/v1/identity-links \
  -H "Authorization: Bearer <token>" \
  -d '{
    "platform": "slack",
    "external_user_id": "U1234ABCD",
    "external_team_id": "T1234ABCD",
    "user_id": "<zensearch-user-uuid>",
    "team_id": "<zensearch-team-uuid>"
  }'

caution

Users without a linked identity (and no matching email) will see: "Your identity is not linked to ZenSearch. Ask your admin to link your account."

Troubleshooting

Bot Not Responding

• Verify SLACK_BOT_ENABLED=true is set
• Check that the bot is added to the channel
• Verify the Events API URL is reachable from Slack
• Check core-api logs for errors

Identity Not Linked

• Ensure the Slack user has a verified email that matches their ZenSearch account
• Or create an explicit identity link via the API

"Still processing your previous message..."

• The bot processes one message per thread at a time
• Wait for the current response to complete before sending another