diff --git a/ai/slack-bot.mdx b/ai/slack-bot.mdx new file mode 100644 index 000000000..12c55bff5 --- /dev/null +++ b/ai/slack-bot.mdx @@ -0,0 +1,151 @@ +--- +title: "Slack bot" +description: "Get AI-powered documentation assistance directly in Slack" +icon: "slack" +--- + +The Slack bot brings Mintlify's AI assistant directly to your team's Slack workspace, enabling seamless documentation assistance without leaving your communication flow. Team members can ask questions about your documentation and receive intelligent responses with source citations, all within Slack. + +## Features + +### Direct message support +The bot responds to direct messages from team members, providing a private channel for documentation queries and assistance. + +### Real-time notifications +Receive automated notifications about Writer Agent completions, pull request updates, and other documentation-related events directly in your Slack channels. + +### Message formatting +The bot properly handles Slack-specific formatting including: +- **Bold text** using single asterisks +- Links formatted as `` +- User mentions as `<@USER_ID>` +- Channel references as `<#CHANNEL_ID>` + +### Intelligent responses +Powered by the same AI technology as the web assistant, the Slack bot provides: +- Contextual answers from your documentation +- Source citations with navigable links +- Code examples when relevant + +## Setting up the Slack bot + +### Prerequisites +- Pro or Custom Mintlify plan +- Slack workspace admin permissions +- Access to your Mintlify dashboard + +### Installation steps + +1. **Create a Slack app** + - Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app + - Choose "From scratch" and select your workspace + +2. **Configure OAuth scopes** + Add the following bot token scopes in your Slack app settings: + - `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 + - `app_mentions:read` - Read mentions of the bot + +3. **Set up event subscriptions** + Configure these bot event subscriptions in your Slack app: + - `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 + +4. **Configure the request URL** + Set your event subscription request URL to your Mintlify webhook endpoint (provided in your dashboard). + +5. **Install the app** + Install the app to your workspace and copy the bot token. + +6. **Connect to Mintlify** + In your Mintlify dashboard, navigate to the Slack integration settings and provide your bot token and signing secret. + +## Using the Slack bot + +### Direct messages +Send a direct message to the bot with any question about your documentation. The bot will search your docs and provide a comprehensive answer with source links. + +**Example:** +``` +How do I set up custom domains? +``` + +The bot will respond with relevant information from your documentation and provide links to the specific pages for more details. + +### Channel mentions +Mention the bot in any channel where it's been added to get documentation assistance in context. + +**Example:** +``` +@docs-bot How do I configure authentication? +``` + +### Notifications +The bot automatically sends notifications for: +- Writer Agent task completions +- Documentation build status updates +- Pull request reviews and merges + +## Dashboard integration + +The Slack bot integrates with your Mintlify dashboard to provide: + +### Real-time status display +View the current status of your Slack bot integration, including connection health and recent activity. + +### Message analytics +Track bot usage patterns, popular queries, and response effectiveness to understand how your team uses documentation. + +### Configuration management +Manage bot settings, notification preferences, and channel configurations directly from your dashboard. + +## Best practices + +### Channel organization +- Add the bot to relevant channels where documentation questions commonly arise +- Create dedicated channels for documentation discussions +- Use thread replies to keep conversations organized + +### Query optimization +- Ask specific questions for better responses +- Include context when asking about implementation details +- Use the bot for quick lookups rather than complex troubleshooting + +### Team adoption +- Introduce the bot to your team with example queries +- Share useful responses in channels to demonstrate value +- Encourage team members to use the bot for self-service documentation + +## Troubleshooting + +### Bot not responding +- Verify the bot token is correctly configured in your dashboard +- Check that required OAuth scopes are granted +- Ensure event subscriptions are properly configured + +### Missing notifications +- Confirm notification settings in your dashboard +- Verify the bot has access to relevant channels +- Check Slack app permissions for the workspace + +### Formatting issues +- The bot automatically handles Slack formatting +- Links and mentions are processed according to Slack standards +- Contact support if you notice persistent formatting problems + +## Privacy and security + +The Slack bot follows the same privacy and security standards as the web assistant: +- Messages are processed securely and not stored permanently +- Only documentation content is used for responses +- Team conversations remain private to your workspace +- All data transmission is encrypted + +For additional security configurations or enterprise requirements, contact your Mintlify account manager. \ No newline at end of file diff --git a/docs.json b/docs.json index 7e738d5e6..c79cc8a08 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",