Slack Bot

Bring GradientHarbor's AI data agent into your Slack workspace. Team members can ask data questions, run queries, and receive charts directly in Slack channels and DMs.

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   Slack          │     │  GradientHarbor  │     │  Your Database   │
│                  │     │                  │     │                  │
│  @GradientHarbor │────▶│  Agent (slack    │────▶│  Execute SQL     │
│  "Top products   │     │  surface)        │     │  against your    │
│   by revenue?"   │     │                  │◀────│  connected DB    │
│                  │◀────│  Format as       │     │                  │
│  📊 Chart posted │     │  Slack blocks    │     │                  │
│  to thread       │     │                  │     │                  │
└──────────────────┘     └──────────────────┘     └──────────────────┘

What the Bot Can Do

• Answer data questions — Ask natural language questions and get SQL-backed answers
• Execute queries — Run queries against your connected databases
• Share results — Post tables and charts as formatted Slack messages
• Thread conversations — Each message creates a dedicated agent thread for follow-up questions

Setup

1. Create a Slack App

1. Go to api.slack.com/apps
2. Click Create New App > From scratch
3. Name it (e.g., "GradientHarbor") and select your workspace
4. Note the following credentials from the Basic Information page:
   • Client ID
   • Client Secret
   • Signing Secret

2. Configure OAuth & Permissions

In your Slack app settings:

1. Go to OAuth & Permissions

2. Add the following Bot Token Scopes:

   • app_mentions:read — Receive mentions in channels
   • chat:write — Post messages
   • im:history — Read DM messages
   • im:read — Access DM channel info
   • im:write — Send DMs
   • users:read — Look up user info
   • users:read.email — Map Slack users to GradientHarbor accounts

3. Set the Redirect URL to:

   https://api.gradientharbor.com/slack/oauth/callback

3. Configure Event Subscriptions

1. Go to Event Subscriptions
2. Enable events
3. Set the Request URL to:

   https://api.gradientharbor.com/slack/events

4. Subscribe to these bot events:
   • app_mention — When someone @mentions the bot in a channel
   • message.im — When someone sends a direct message to the bot

4. Connect in GradientHarbor

1. Go to Administration > Integrations in GradientHarbor
2. Click Connect Slack
3. Authorize the Slack app with your workspace
4. The bot is now active

How It Works

Channel Mentions

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

@GradientHarbor What were our top 10 products by revenue last week?

The bot will:

1. Identify the Slack user's GradientHarbor account (matched by email)
2. Create an agent thread with the slack surface
3. Execute the query using the user's organization context
4. Post the results as a formatted Slack message

Direct Messages

Send a DM directly to the bot for private data questions. The same agent capabilities are available — query execution, table/chart results, and follow-up conversations.

User Mapping

The Slack bot maps Slack users to GradientHarbor accounts by email address. For the bot to respond:

• The Slack user's email must match a GradientHarbor user's email
• That user must be an active member of an organization with Slack integration enabled

WARNING

If a Slack user's email doesn't match any GradientHarbor account, the bot cannot process their requests. Ensure team members use the same email for both platforms.

Limitations

• The Slack bot uses the slack agent surface, which has a slightly different tool set than the web chat
• File attachments via Slack are not currently supported — use the web chat for CSV/PDF/image uploads
• Rate limits apply per Slack's API policies

Troubleshooting

Issue	Solution
Bot doesn't respond	Verify the bot is added to the channel. Check that event subscriptions are configured correctly.
"User not found" error	The Slack user's email doesn't match a GradientHarbor account.
Duplicate responses	Event delivery is deduplicated by event ID. If you see duplicates, check your Slack app's retry settings.
OAuth callback fails	Verify the redirect URL matches exactly: https://api.gradientharbor.com/slack/oauth/callback