diff --git a/ai/slack-bot.mdx b/ai/slack-bot.mdx new file mode 100644 index 000000000..f3e3d0a4a --- /dev/null +++ b/ai/slack-bot.mdx @@ -0,0 +1,155 @@ +--- +title: "Slack bot" +description: "Get Writer Agent notifications and interact with your documentation directly in Slack" +icon: "slack" +--- + + + The Slack bot integration is available on [Pro and Custom plans](https://mintlify.com/pricing?ref=slack-bot). + + +## About the Slack bot + +The Slack bot brings your documentation's Writer Agent capabilities directly into your Slack workspace. It provides real-time notifications when documentation updates are completed and enables direct messaging for documentation assistance. + +The bot integrates with Mintlify's Writer Agent system to: + +* **Send completion notifications** when Writer Agent finishes processing documentation updates +* **Handle direct messages** for documentation questions and assistance +* **Format messages properly** with support for Slack's native formatting (bold text, links, user mentions, channel references) +* **Display pull request links** and other relevant information in a user-friendly format + +## Setting up the Slack bot + +### Prerequisites + +Before setting up the Slack bot, ensure you have: + +* A Slack workspace with admin permissions +* A Mintlify Pro or Custom plan +* Access to your Slack app configuration + +### Required OAuth scopes + +Configure your Slack app with the following OAuth scopes for full functionality: + +#### Bot token scopes +* `im:read` - Read DM channel information +* `im:write` - Send DM responses +* `im:history` - **Critical:** Receive DM message events +* `channels:history` - Receive channel message events +* `groups:history` - Receive private channel events +* `mpim:history` - Receive group DM events + +### Event subscriptions + +Configure these bot event subscriptions in your Slack app settings: + +* `message.im` - Direct message events +* `message.channels` - Public channel messages +* `message.groups` - Private channel messages +* `message.mpim` - Group DM messages +* `app_mention` - When the bot is mentioned + +### Installation steps + +1. **Create a Slack app** in your workspace or use an existing one +2. **Configure OAuth scopes** as listed above +3. **Set up event subscriptions** for the required message events +4. **Install the app** to your workspace +5. **Connect to Mintlify** through your dashboard settings + +## Using the Slack bot + +### Direct messaging + +You can send direct messages to the bot for documentation assistance: + +1. **Find the bot** in your Slack workspace +2. **Send a direct message** with your question or request +3. **Receive responses** with relevant documentation information + +The bot will respond to direct messages and exclude its own messages to prevent loops. + +### Notification display + +The bot automatically sends notifications to configured channels when: + +* Writer Agent completes documentation updates +* Pull requests are processed +* Documentation builds finish + +### Message formatting + +The bot properly handles Slack's native formatting: + +* **Bold text** using single asterisks (`*bold*`) +* **Links** formatted as `` +* **User mentions** as `<@USER_ID>` +* **Channel references** as `<#CHANNEL_ID>` + +## Dashboard integration + +Monitor your Slack bot activity through the Mintlify dashboard: + +### Real-time status + +View the current status of your Slack bot integration, including: + +* Connection status +* Recent activity +* Message delivery status + +### Notification settings + +Configure which events trigger Slack notifications: + +* Writer Agent completion notifications +* Documentation build status +* Error alerts and warnings + +### Message history + +Review recent bot interactions and notifications sent to your Slack workspace. + +## Troubleshooting + +### Bot not responding to direct messages + +1. **Verify OAuth scopes** - Ensure `im:history` scope is enabled +2. **Check event subscriptions** - Confirm `message.im` events are configured +3. **Reinstall the app** if permissions were recently changed + +### Missing notifications + +1. **Review notification settings** in your Mintlify dashboard +2. **Check channel permissions** - Ensure the bot can post to target channels +3. **Verify webhook URLs** are correctly configured + +### Message formatting issues + +The bot automatically handles Slack formatting. If messages appear incorrectly: + +1. **Check message content** for unsupported formatting +2. **Review channel settings** for any message restrictions +3. **Contact support** if formatting issues persist + +## Best practices + +### Channel organization + +* **Dedicate channels** for documentation notifications +* **Use threading** for related discussions +* **Pin important** bot messages for easy reference + +### User engagement + +* **Train team members** on how to interact with the bot +* **Share documentation links** from bot responses +* **Use mentions** to involve relevant team members in discussions + +### Monitoring + +* **Review bot activity** regularly through the dashboard +* **Monitor message volume** to understand usage patterns +* **Adjust notification settings** based on team feedback \ No newline at end of file diff --git a/changelog.mdx b/changelog.mdx index 92d56b10e..4acc4ae17 100644 --- a/changelog.mdx +++ b/changelog.mdx @@ -5,7 +5,16 @@ rss: true noindex: true --- - + + +## New Slack bot integration + +- **Major release**: Slack bot for instant documentation access - responds to DMs, @mentions, and questions in your `#ask-ai` channel +- Zero-friction setup with one-click installation directly from your Mintlify dashboard +- Contextual answers by searching your entire documentation to provide relevant, accurate responses +- Deflect support interruptions by turning daily questions into instant, self-serve answers + +Learn more in our [Slack bot guide](/ai/slack-bot). ## GitLab integration enhancements diff --git a/docs.json b/docs.json index b451ec3d7..5b903d1b6 100644 --- a/docs.json +++ b/docs.json @@ -51,6 +51,7 @@ "group": "AI optimization", "pages": [ "guides/assistant", + "ai/slack-bot", "ai/llmstxt", "ai/contextual-menu", "ai/model-context-protocol",