Connect a chatbot to Slack so your team can ask it questions by mentioning it in a channel or messaging it directly. You create a Slack app in your own workspace — no Slack app-directory review is involved. Pro plan only.

Before You Start

• A Slack workspace where you can install apps. If your workspace requires admin approval, you will need an admin.
• A chatbot in Aimy with at least one document uploaded.

Step 1 — Create the Slack app

1. Start a new app. Go to api.slack.com/apps → Create New App → From scratch. Name it and pick your workspace.

2. Add the bot scope. Open OAuth & Permissions, scroll to Bot Token Scopes, and add chat:write. That is the only scope required to answer.

Add these too if you want the bot to work everywhere:

• app_mentions:read — so it can see mentions in channels.
• im:history — so it can see direct messages.

3. Install it. Scroll up and click Install to Workspace, then approve.

4. Copy the bot token. Back on OAuth & Permissions, copy the Bot User OAuth Token. It starts with xoxb-.

5. Copy the signing secret. Open Basic Information → App Credentials → Signing Secret → Show, and copy it.

Step 2 — Connect in Aimy

6. Open the integration. Integrations → the Slack card → pick your chatbot from the tabs.

7. Paste both values into Bot user OAuth token and Signing secret, then click Connect.

Verify: Aimy calls Slack to check the token before storing it. On success the status pill shows your workspace name. Seeing the right workspace name is the proof — not just the absence of an error.

Step 3 — Point Slack at the Request URL

8. Copy the Request URL from the box that appears after connecting.

9. Paste it into Slack. In your app, open Event Subscriptions, turn Enable Events on, and paste the URL into Request URL.

Verify: Slack immediately sends a challenge and shows a green Verified next to the field. If it does not verify, the signing secret is wrong — that handshake is signature-checked like any other request.

10. Subscribe to events. Still on that page, expand Subscribe to bot events and add:

• app_mention — someone @mentions the bot in a channel.
• message.im — someone sends the bot a direct message.

11. Save, then reinstall. Click Save Changes. Slack will show a banner asking you to reinstall the app — do it, or the new events never arrive.

Step 4 — Test it

12. Invite the bot to a channel. In Slack, type /invite @YourBotName in a channel. A bot that is not in the channel cannot reply there.

13. Ask it something. Mention it with a real question: @YourBot what is our refund policy?

Verify: the answer arrives in a thread under your question, not as a new channel message. That threading is deliberate — it keeps long answers out of the main channel flow.

14. Test a DM too. Open a direct message with the bot and ask without mentioning it. This exercises message.im separately.

How it works — and why replies are not instant

Slack requires a response within three seconds and retries if it does not get one. Our answers routinely take longer, so Slack is answered in two stages: the webhook acknowledges immediately, and a background worker posts the real answer afterwards through chat.postMessage.

This is why a Slack connection can look perfect while replies never arrive — the connection and the reply are different code paths. If Step 13 produces silence, look for channel_reply_worker in the error log, not slack_webhook.

Each Slack thread is its own conversation. Long answers are split at about 3,500 characters.

Troubleshooting

• Request URL will not verify. Wrong signing secret, or the server clock is off — requests more than five minutes old are rejected as replays.
• "The bot is not in that channel — invite it first." Exactly what it says. Run /invite.
• "The Slack app is missing a required scope." Add chat:write and reinstall.
• Mentions work, DMs do not. message.im was not subscribed, or the app was not reinstalled after adding it.
• No reply, no errors. The webhook acknowledged but the worker did not run. Check /tmp/aimy_channel_jobs/ — files piling up means the worker is not starting.