Add Slack Bot Integration Documentation

changelog.mdx

@@ -5,6 +5,21 @@
 noindex: true
 ---
 
+<Update label="September 20 - September 26" tags={["New releases"]} rss={{ title: "Weekly Updates", description: "Slack bot integration for Writer Agent, direct messaging support, and enhanced notification system" }}>
+
+## Major release: Slack bot integration
+
+- **Major enhancement**: Comprehensive Slack bot integration for Writer Agent system with direct messaging and automated notifications
+- Bot responds to direct messages (DMs), @mentions, and messages in designated channels
+- Real-time display of Writer Agent completion notifications in dashboard
+- Enhanced OAuth scopes including `im:read`, `im:write`, `im:history`, and channel history permissions
+- Event subscriptions for `message.im`, `message.channels`, `message.groups`, `message.mpim`, and `app_mention`
+- Proper message formatting for Slack-style text including bold text, links, user mentions, and channel references
+
+Learn more in our [Slack integration guide](/integrations/support/slack).
+
+</Update>
+
 <Update label="September 14 - September 19" tags={["Improvements"]} rss={{ title: "Weekly Updates", description: "GitLab integration enhancements, app router migration progress, authentication improvements, and bug fixes" }}>
 
 ## GitLab integration enhancements
@@ -20,11 +35,11 @@
 
 ## Bug fixes and reliability
 
 - Fixed app router socket update functionality for real-time features
 - Fixed SVG path rendering issues in documentation
 - Fixed keyboard navigation in search and chat functionality
 - Fixed history status endpoint reliability
 - Resolved middleware edge cases and onClick event handling issues
 
 </Update>
 
@@ -34,14 +49,14 @@
 
 - **Major enhancement**: AI suggested pages on 404 pages, [when someone hits a dead link → AI agent reads the path → suggests semantically similar pages](https://x.com/mintlify/status/1966625627773059495)
 - **Major release**: web search for assistant can now include external sources  
   _Note: Contact us to enable this feature for your site._
 
 ## Assistant and MCP
 
 - Fixed a bug where the assistant would be incorrectly rate limited due to time window not sliding correctly
 - Fixed a bug with assistant tool calling to properly handle empty `text` blocks
 - Fixed a bug where MCP server name's concatenated with tool calls were sometimes exceeding the 60 character length MCP clients enforce
 - Fixed a bug where the assistant menu would have a height several times larger than the viewport and scroll forever
 - Fixed a bug where assistant spend values could display with greater than two decimal places in the dashboard
 
 ## Web editor and deployments
@@ -49,20 +64,20 @@
 - Security enhancement added to editor such that only users with `write permissions` for the connected git hosting repository can make changes
 - Fixed a bug where preview deployments wouldn't work for branches with `=` in the name
 - Fixed a bug where long branch names would overflow modals on preview deployment creations
 - Quality of life improvement where email query parameter will prefill the input on signup invitations
 - Fixed a bug where copying a page from the context menu was not working on safari 
 
 ## API playground and navigation
 
 - Multiple API playground response codes now display in a controlled styled select menu instead of the system default select menu when focused
 - You can now use the [`expanded` field on navigation groups in your `docs.json` to make them be default open](https://mintlify.com/docs/navigation#default-expanded-state)
 
 ## SEO and UI
 
 - Fixed a bug where favicons were not showing up in search engines by serving them from the same URL as the documentation site itself for each respective site
 - Fixed a bug where youtube embeds would flash in and out on load
 - Fixed a bug where expanding the feedback menu to include written responses would cause layout shift with the table of contents
 - Fixed a bug where text would leak above the topbar on the maple theme when a dismissed the notification banner
 - Enhanced the Maple and Willow themes by adding login/logout buttons to the sidebar for easier access 
 
 ## Analytics and exports
@@ -77,7 +92,7 @@
 ## Major release: Enhanced feedback collection
 
 - **Major improvement**: Readers can now give more detailed feedback after selecting *thumbs up/down*, including options and written comments. You can also collect feedback on code blocks and view all responses in your dashboard analytics.  
   _Note: Contact us to enable this feature for your site._
 
 ## Navigation and quality of life improvements
 
@@ -93,16 +108,16 @@
 - Fixed a bug where Google was indexing raw `*.md` files because they were missing a `x-robots-tag noindex` header
 - Fixed a bug with OAuth on protected docs where it wouldn't redirect you back to your starting page once you completed the flow successfully
 - Fixed a bug on previews of auth protected docs where you weren't able to see the entire navigation bar
 - Bug fixes to how SVGs are handled with our new image CDN  
 
 ## Component and styling enhancements
 
 - Added a new CSS selector for custom styles on `SidebarNavGroupDivider`  
 - New regression tests for MDX defined API pages that have security defined on them will ensure a greater degree of stability
 
 ## Performance improvements
 
 - Performance improvement by moving the KaTeX CSS from cdnjs to our own CDN on Cloudfront for reduced latency
 
 </Update>
 
@@ -111,18 +126,18 @@
 ## Image handling improvements
 
 - **Major improvement**: Images no longer cause layout shift by default, even when width and height attributes aren't specified—automatic sizing prevents content jumping during page loads
 - All static files in your repository (PDF, TXT, XML, etc.) are now automatically uploaded and served when you deploy, providing complete asset coverage
 
 ## Web editor and deployment enhancements
 
 - Fixed branch creation workflow in web editor to correctly navigate to and stay on newly created branches
 - Enhanced merge conflict dialog with proper escape functionality, no more page reloads required to dismiss conflicts
 - Optimized update workflow performance by cache-invalidating only changed pages during partial updates, reducing deployment times
 
 ## Authentication and navigation improvements
 
 - New support for authentication on custom subdirectories, if you serve docs at `https://yourdomain.com/docs`, authentication now works seamlessly
 - Fixed sidebar display bug that incorrectly showed when only one link was configured
 - Comprehensive mobile navigation overhaul: centered buttons with proper margin/padding, improved spacing in dropdown menus, removed unnecessary dividers and margins for empty sections, and fixed Maple theme gap/padding issues
 
 ## Component and styling fixes
@@ -134,7 +149,7 @@
 
 - Enhanced logging system for update workflows enabling faster debugging and issue resolution
 - Fixed GitHub rate limiting for customers with 10+ OpenAPI/AsyncAPI specs by switching from individual file fetching to repository cloning
 - Improved assistant reliability with backup LLM support, enhanced rate limit error handling, and more robust search tool functionality
 
 </Update>
 
@@ -143,16 +158,16 @@
 ## Performance and build optimizations
 
 - MDX transpilation now happens at deployment time instead of on every page load in uncached NextJS serverless environments, improving time to first byte for uncached pages.
 - Content-based hashing prevents re-transpilation when MDX hasn't changed, reducing update workflow times by ~50% for customers with large page counts (deployments over 5 minutes should be roughly halved)
 - Preview deployment viewing in the dashboard is now faster with added database indexes and query parallelization in our backend
 - Reduced page size by eliminating duplicate `navigation` data in each page's `rsc` payload—performance gains most noticeable with high page counts or complex navigation structures
 - More aggressive prefetching enables instant page loads more frequently
 
 ## API playground and OpenAPI enhancements
 
 - OpenAPI to MCP conversion moved to backend, enabling hosted MCP servers to contain tools (expect clearer documentation and config options soon)
 - Added Ruby support to API playground
 - We added a feature such that you can now [specify API pages using just your docs.json](/api-playground/openapi-setup#auto-populate-api-pages) without creating any new mdx files.
 - Support for [`webhook` pages](/api-playground/openapi-setup#webhooks) in docs navigation from OpenAPI specs
 - Optimized AI model context by removing anchor link specifications from markdown links when navigating to Anthropic, OpenAI, or other providers
 
@@ -161,18 +176,18 @@
 - File creation/renaming now saves changes when clicking away instead of requiring Enter key press
 - Fixed branch navigation where changing URL to specific branch would redirect to last active branch instead of intended destination
 - Properly URL encode branch titles containing `/` to prevent navigation breakage
 - Fixed `Ctrl+K` link shortcut in monorepo dashboard Editor that was prepending docs repo path and creating broken links
 
 ## Analytics and LLM integrations
 
 - Custom `llms.txt` and `llms-full.txt` support—add to docs repo root to serve at `/llms.txt` and `/llms-full.txt` endpoints for LLM customization
 - Added [Hightouch analytics integration](/integrations/analytics/hightouch#hightouch)
 - Enhanced context menu analytics tracking (dashboard viewing coming soon)
 - Added e2e tests for `llms.txt` and `llms-full.txt` to ensure correct serving
 
 ## Component and styling enhancements
 
 - Support for custom classnames in `h{1-4}` tags for applying custom heading styles
 - Fixed `h{1-4}` tags rendering as `Heading` components with chips in custom page mode
 - Added CSS selectors to [breadcrumbs](/navigation#breadcrumbs) for custom CSS targeting
 - Fixed stretched open-graph images by analyzing dimensions to maintain proportions at 56px height
@@ -182,10 +197,10 @@
 ## Bug fixes and reliability
 
 - Fixed PDF render issues with certain page titles by sanitizing characters that cause generation problems
 - Resolved CLI error `Cannot convert undefined or null to object` when encountering empty OpenAPI JSON files
 - Fixed custom `docs.json` open-graph metatags being overwritten by generated ones
 - Fixed RSS feed button clicks when landing on anchor links by using origin + pathname for RSS links
 - Improved CLI download speed by removing sourcemaps
 
 ## Technical improvements
 
@@ -200,40 +215,40 @@
 
   - Group-level public access: make entire page groups public via `docs.json` so you don’t need `public: true` on each page ([learn more](https://mintlify.com/docs/authentication-personalization/authentication-setup#group-level))
   - Support [`logoutURL` in OAuth configuration](https://mintlify.com/docs/authentication-personalization/authentication-setup#implementation-3) to delete upstream cookies and complete sign-out
   - On OAuth errors, users are redirected to your specified `logoutURL` to restart the auth flow
   - Fixed a flash of a 500 error during OAuth/JWT flows before the callback
   - Auto-strip `https://` from URLs in OAuth/JWT auth configuration to prevent misconfiguration
 
   ## API playground enhancements
 
   - New [Search API endpoint](https://mintlify.com/docs/api-reference/assistant/search) so you can build agents and MCP servers on top of your docs
   - `openapi` and `asyncapi` files are now served at their specified paths (for example, `https://mydocsurl.extension/{openapi-or-file-name}.json`)
   - You can now use the [`x-mint` field in your openapi files](https://mintlify.com/docs/api-playground/openapi-setup#x-mint-extension) to override generated fields, customize preface content, or change endpoint URLs in code samples
   - [`x-mcp` is now `x-mint.mcp`](https://mintlify.com/docs/api-playground/openapi-setup#mcp) in OpenAPI configurations to control which routes are exposed as MCP tools
 
   ## Assistant updates
 
   - Fixed an issue where the action menu (containing options like copy and thumbs up) for older messages disappeared when new ones streamed in
   - Fixed accessibility of nested `/mcp/...` pages after the [hosted MCP servers release](https://mintlify.com/docs/ai/model-context-protocol#accessing-your-mcp-server) from last week
 
   ## Performance and reliability
 
   - All image and video assets present in your docs repo are now served at the appropriate path on your domain. For example, if you have `/assets/marketing/my-logo.png` in your repo, it will be available at `https://mydocsurl.extension/assets/marketing/my-logo.png`.
   - Email field on login for the Mintlify dashboard now autofocuses so you can start typing immediately _(quality of life improvement)_
   - Both custom domains and subdomains in Redis for a performance improvement on navigation load times (~50ms latency reduction)
   - Added retry logic for PDF exports to improve reliability
   - Fixed cookie consent popup reappearing after acceptance or dismissal—first selection is now respected
   - Fixed copying a page to clipboard on Safari by specifying a MIME `type` in `navigator.write`
 
   ## Technical improvements
 
   - CLI bugfixes for windows and pnpm, plus CI tests to prevent regressions
   - Improved error logging output—a quality of life upgrade for our engineering team when debugging
   - Minor fixes to the broken-link CI action when `contentDirectory` files are missing
   - Fixed a regression caused by the auth-protected preview fixes from last week where the active tab was not being set correctly in the navigation UI
   - Fixed theme light background color not being applied to active tab icons
   - Fixed an issue where changing the auth type in the dashboard would update and then flip back to the previously saved type—now the new selection persists after saving
   - Internal DX improvements for enterprise customers with custom UI libraries—it's now easier for us to include your components and accommodate requests on shorter timelines
 </Update>
 
 <Update label="July 27 - August 2" tags={["Improvements"]} rss={{ title: "Weekly Updates", description: "Authentication improvements, search enhancements, and assistant API" }}>
@@ -242,11 +257,11 @@
   - Local development improvements to auth, enabling faster development of auth features and bug fixes in this product area
   - Preview deployments now available for auth-protected sites
   - Fixed redirect behavior to properly return users to their original page after authentication
   - Fixed logout button display for full authentication (previously only worked for partial authentication)
 
   ## API playground enhancements
 
   - Fixed `multipart/form-data` file upload functionality in the API playground
   - Fixed anchor link behavior so clicking them updates the URL without scrolling to top of page
   - Fixed anchor link issues in nested tabs
 
@@ -258,15 +273,15 @@
 
   ## Performance and reliability
 
   - Made search feel more crisp and accurate by aborting debounced requests as you type
   - Resource provisions for a new CDN - expect image asset and page load times to improve soon
   - Fixed bugs for rendering complex Mermaid diagrams like GANTT charts
   - Fixed CLI bugs on Windows to improve stability and added tests to prevent regression
 
   ## Technical improvements
 
   - Added OpenTelemetry for traces in NextJS application to improve time to first byte for customers
   - Migrated from Octokit to GitHub API Client to improve latency in the web editor experience
   - Fixed duplicate meta tags for OpenGraph
   - Upgraded MongoDB from version 6 to 7 for improved performance and new features
 </Update>
@@ -274,16 +289,16 @@
 <Update label="July 2025" tags={["New releases", "Improvements"]} rss={{ title: "July Product Updates", description: "Slack app integration, hosted MCP servers, Cursor integration, and performance improvements" }}>
   ## Slack app
 
   - Zero friction access: Bot responds to DMs, @mentions, and any question in your `#ask-ai` channel
   - One-click setup: Install directly from your Mintlify dashboard in seconds
   - Contextual answers: Searches your entire documentation to provide relevant, accurate responses
   - Deflect support interruptions: Turn daily questions into instant, self-serve answers
 
   Learn more in our [Slack app guide](/ai/slack-app).
 
   ## Hosted MCP servers
 
   Deploy hosted Model Context Protocol (MCP) servers directly through Mintlify to integrate with AI tool like Claude, Cursor, and others. Learn more in our [MCP guide](/ai/model-context-protocol).
 
   Help users quickly connect your MCP server to Cursor or VS Code from any page in your docs via the contextual menu. See [Contextual menu](/ai/contextual-menu) for more information.
 
@@ -296,7 +311,7 @@
 <Update label="June 2025" tags={["New releases", "Improvements"]} rss={{ title: "June Product Updates", description: "AI assistant updates and subscribable changelogs" }}>
   ## AI assistant updates
 
   - Improved accuracy through agentic RAG with tool calling
   - Provides navigable links to referenced pages so that users can go directly to the source of answers
   - Copy shortcut for code examples generated by assistant
   - "Ask AI" shortcut on code blocks in documentation to generate explanations from the assistant
@@ -304,10 +319,10 @@
   Learn more in the [assistant docs](/guides/assistant).
 
   ## Subscribable changelogs
   - Automatically generate an RSS feed from changelog pages
   - Integrate RSS-enabled updates with Slack, email, and other tools
 
   Learn more in our new [Changelog guide](/guides/changelogs)
 
 </Update>
 
@@ -322,14 +337,14 @@
   Learn more at [API playground docs.](/api-playground/)
 
   ## `mint update`
   Can now use `mint update` to update your CLI.
 </Update>
 
 <Update label="April 2025" tags={["New releases", "Improvements"]}>
   ## Web Editor 3.0
 
   <Frame>
     ![Webeditor3 Jpe](/images/webeditor3.jpeg)
   </Frame>
   Overhauled usability in the WYSIWYG editor.
 
@@ -338,21 +353,21 @@
   - Search for file names using ⌘ \+ P shortcut
   - Pages load 10x faster
   - Faster load times when searching for a branch
   - Page options tab to configure layout, title, & metadata for SEO
   - Floating toolbar when you highlight text
 
   **Additional fixes**
 
   - Fixed top margin for changelog components
   - Improved reliability of right click behavior
   - After clicking publish, you’ll stay on the same page instead of being brought to an empty state
   - Standardized colors in file icons
   - Improved reliability after selecting new branches several times in a row
   - Removed Diff mode
   - More consistency when creating a new folder from the dropdown
   - Fixed block quotes creating more block quotes when trying to deselect
 
   ## AI Translations in beta
 
   <Frame>
     ![AI Translations graphic](/images/changelog/translations.png)
@@ -387,10 +402,10 @@
 
   - OG images fixed
   - Fixed icon style inconsistency for anchors without container
   - Improved styling nits for dashboard border for mobile-tablet-desktop responsiveness
   - Show code examples even when in simple mode for API playground
   - Support "command \+ k" shortcut for search in web editor
   - Codeblocks within callouts expand to fill the width of the callout area
 </Update>
 
 <Update label="February 2025" tags={["New releases", "Improvements"]}>
@@ -403,7 +418,7 @@
 
   Upgrade from `mint.json` to `docs.json` with the following steps:
 
   1. Make sure your CLI is the latest version
 
   ```bash
   npm i mint@latest -g
@@ -417,15 +432,15 @@
 
   1. Delete your old `mint.json` file and push your changes
 
   ## CI Checks
 
   Automatically lint your docs to find broken links, discover spelling and grammar issues, or enforce writing styles with your own Vale config. Learn more in our [docs](settings/ci).
 
   ## .md support for LLMs
 
   All documentation pages are now automatically available as plain Markdown files—just append `.md` to the URL. This makes it easier for LLMs to ingest individual pages from your documentation.
 
   ## More Themes
 
   <Frame>
     ![graphic with text "Themes v2"](/images/changelog/themes.png)
@@ -442,24 +457,24 @@
 
   - [Guide to Technical Writing:](https://mintlify.com/guides/introduction)Best practices for writing technical documentation, including audience research, content types, and writing tips.
   - [Dropdown component](navigation#dropdowns): Organize navigation with a dropdown, in addition to tabs and anchors.
   - [AI syntax fixer](https://x.com/ricardonunez_io/status/1892334887644123192): The web editor will catch if there’s a parsing error and use AI to suggest fixes.
 </Update>
 
 <Update label="January 2025" tags={["Improvements"]}>
   ## AI Assistant Improvements
 
   - New UI with dedicated chat page & pre-filled prompts
   - Stability improvements. For example, bug fixes of editing the wrong file or no files at all
   - More robust knowledge for adding & editing components
   - Improved `docs.json` file editing
 
   ## Partial Authentication
 
   Customize access to any page or section of content depending on user permissions. Supports connecting with your own authentication system.
 
   ## Revamped API Playground
 
   We’ve overhauled the design and performance of the [API Playground](/api-playground/). Updates include:
 
   - Easier detail expansion for an overview of a field
   - More intuitive nested design. For example, adding or deleting items
@@ -480,27 +495,27 @@
 </Update>
 
 <Update label="November 2024">
   ## AI Writer
 
   <Frame>
     ![AI Assistant](/images/changelog/ai-assistant.jpg)
   </Frame>
   You can now ask AI to make changes to your docs, with the context of all existing documentation. Type in a prompt and the writer will propose changes by generating a pull request.
 
   ## GitLab Integration Upgrade
 
   We've improved our support for syncing with GitLab, such as enabling automated updates and preview deployments. Check out our [docs on GitLab](/settings/gitlab) to get started.
 
   ## Web Editor
 
   <Frame>
     ![Web Editor](/images/changelog/webeditor.jpg)
   </Frame>
   We've revamped our web editor so that you can now update docs with a fully WYSIWYG experience, while syncing with markdown.
 
   Check out our [docs on getting started with Web Editor](/editor).
 
   ## /llms.txt support
 
   <Frame>
     ![llms.txt support](/images/changelog/llms.jpg)
@@ -509,30 +524,30 @@
 
   ## Localization
 
   You can now localize your docs which operates similarly to versioning. Add a `locale` to a version and fixed content in Mintlify like "Was this page helpful?" will also match the locale.
 
   ### Quality Improvements
 
   - Return chat & search results based on the current version that the user is reading
   - Authenticate users with OAuth, in addition to JWT or Shared Session tokens.
 </Update>
 
 <Update label="October 2024">
   ## Changelogs
 
   Launched a new [Update component](/components/update) to make it easier to display and report updates (like this one) to your users.
 
   <Frame>
     ![Changelog](/images/changelog/changelog.jpg)
   </Frame>
   ## Code Line Highlighting
 
   You can now highlight lines of code in your docs to emphasize and bring attention to important parts by adding a special comment after the language identifier. Use curly braces `{}` and specify line numbers or ranges separated by commas.
 
   ```javascript Line Highlighting Example {1,3-5}
   const greeting = "Hello, World!";
   function sayHello() {
     console.log(greeting);
   }
   sayHello();
   ```

docs.json

@@ -216,6 +216,7 @@
                     "icon": "messages-square",
                     "pages": [
                       "integrations/support/overview",
+                      "integrations/support/slack",
                       "integrations/support/intercom",
                       "integrations/support/front"
                     ]
@@ -483,6 +484,7 @@
                     "icon": "messages-square",
                     "pages": [
                       "fr/integrations/support/overview",
+                      "integrations/support/slack",
                       "fr/integrations/support/intercom",
                       "fr/integrations/support/front"
                     ]
@@ -750,6 +752,7 @@
                     "icon": "messages-square",
                     "pages": [
                       "es/integrations/support/overview",
+                      "integrations/support/slack",
                       "es/integrations/support/intercom",
                       "es/integrations/support/front"
                     ]
@@ -1017,6 +1020,7 @@
                     "icon": "messages-square",
                     "pages": [
                       "zh/integrations/support/overview",
+                      "integrations/support/slack",
                       "zh/integrations/support/intercom",
                       "zh/integrations/support/front"
                     ]

integrations/support/overview.mdx

@@ -4,6 +4,13 @@ description: "Integrate with a support widget"
 ---
 
 <CardGroup>
+  <Card
+    title="Slack"
+    href="/integrations/support/slack"
+    icon="slack"
+    horizontal
+    >
+  </Card>
   <Card
     title="Intercom"
     href="/integrations/support/intercom"

integrations/support/slack.mdx

@@ -0,0 +1,118 @@
+---
+title: "Slack"
+description: "Integrate with Slack for Writer Agent notifications and direct messaging"
+icon: "slack"
+---
+
+<Info>
+  The Slack integration is available for Writer Agent users and enables direct messaging and automated notifications.
+</Info>
+
+## About the Slack integration
+
+The Slack integration connects your Writer Agent system with Slack, enabling:
+
+- **Direct message handling** - Bot responds to direct messages from users
+- **Automated notifications** - Writer Agent completion notifications sent to Slack
+- **Real-time status updates** - Display of Writer Agent status in your dashboard
+- **Formatted messaging** - Proper rendering of Slack-formatted content including links, mentions, and channels
+
+## Setting up the Slack integration
+
+### Prerequisites
+
+- Active Slack workspace with admin permissions
+- Writer Agent system configured
+- Access to Slack app configuration
+
+### 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 in your app's OAuth & Permissions section
+3. **Set up event subscriptions** in your app's Event Subscriptions section
+4. **Install the app** to your workspace to generate the bot token
+5. **Configure your Writer Agent** system with the Slack app credentials
+
+## Using the Slack integration
+
+### Direct messaging
+
+Users can send direct messages to the Slack bot, which will:
+
+- Process the message through the Writer Agent system
+- Respond with relevant information or actions
+- Filter out bot messages to prevent loops
+- Handle type-safe message processing
+
+### Notifications
+
+The integration automatically sends notifications for:
+
+- Writer Agent task completions
+- Pull request updates and links
+- System status changes
+- Error notifications and alerts
+
+### Message formatting
+
+The integration properly handles Slack's message formatting:
+
+- **Bold text** using single asterisks (`*bold*`)
+- **Links** formatted as `<url|display text>`
+- **User mentions** as `<@USER_ID>`
+- **Channel references** as `<#CHANNEL_ID>`
+
+### Dashboard integration
+
+The Slack integration displays in your dashboard:
+
+- Real-time bot status
+- Writer Agent completion notifications
+- Formatted pull request links
+- Message history and analytics
+
+## Troubleshooting
+
+### Bot not responding to DMs
+
+Ensure you have configured the `im:history` scope - this is critical for receiving DM message events.
+
+### Missing notifications
+
+Verify that:
+- Event subscriptions are properly configured
+- The bot is installed in your workspace
+- OAuth scopes include all required permissions
+
+### Formatting issues
+
+Check that your Slack app has the correct permissions to read and write messages in the channels where formatting issues occur.
+
+## Security considerations
+
+- Bot tokens should be stored securely and rotated regularly
+- Limit bot permissions to only required scopes
+- Monitor bot activity through Slack's audit logs
+- Review message handling to ensure sensitive information is protected