mintlify__docs/agent/slack.mdx

---
title: "Add the agent to Slack"
description: "Add the Mintlify agent to Slack to ask questions about your docs, create documentation updates from conversations, and capture team knowledge."
keywords: ["Slack integration", "Slack bot", "team collaboration", "agent integration", "knowledge capture"]
---

<Note>
  If your Slack Workspace Owner requires admin approval to install apps, ask them to approve the Mintlify app before you connect it.
</Note>

## Connect your Slack workspace

1. Go to the [Agent](https://app.mintlify.com/products/agent) page in your dashboard.
2. In the "Agent settings" section, click **Install Slack app**.
  <Frame>
    <img src="/images/agent/install-apps-light.png" alt="The App settings section with the Slack and Notion install buttons." className="block dark:hidden" />
    <img src="/images/agent/install-apps-dark.png" alt="The App settings section with the Slack and Notion install buttons." className="hidden dark:block" />
  </Frame>
3. Follow the Slack prompts to install the `mintlify` app in your workspace and grant the requested permissions.
4. Confirm the connection in your Mintlify dashboard to your Slack workspace.
5. Test that the agent is working and responds when you:
   - Send a direct message to the agent.
   - Mention the agent with `@mintlify` in a channel.

<Note>
  Each Slack workspace can connect to only one Mintlify organization at a time. If you try to install the agent into a workspace that is already connected to a different organization, the installation fails with a "wrong organization" error. Uninstall the app from the other organization first, or use a different Slack workspace.

  You can install the Slack agent even if you don't have a Mintlify-hosted deployment. The agent still works for question answering and conversations; features that open pull requests require a connected repository.
</Note>

### Reconnect or reinstall the agent

If you must reauthorize the agent—for example, to grant new permissions after a Slack scope update or to recover from a revoked token—reinstall the app from your Mintlify dashboard.

When you reinstall the agent into a workspace that is already connected to your organization, Mintlify refreshes the stored bot token in place. Your existing channels, threads, and per-user integrations remain intact.

<Tip>
If your organization has multiple deployments, the agent asks you to choose which deployment to work with the first time you send a request.

Your preferred deployment is personal to your Slack account and does not affect
other team members. You can switch to a different deployment at any time during a
conversation by clicking the **Switch deployment** button on the agent's status
message in the thread. The agent retains your conversation history so you can
continue where you left off with the new deployment.
</Tip>

## Use the agent in Slack

Once connected, you can:

- Send direct messages to the agent to use it privately.
- Mention `@mintlify` in a channel to use it publicly and collaboratively.
- Attach files and images directly to your messages for the agent to process and include in your docs.
- Continue conversations in threads to iterate on changes or ask follow-up questions. The agent reuses files, images, and emoji reactions from earlier in the thread as context for follow-up requests, so you don't have to reupload them.
- Share pull request links with the agent to update related documentation.

## Ask questions about your docs

Ask the agent questions about your product or documentation and receive answers in the thread.

- **New question**: Send a direct message to the agent or mention `@mintlify` in a channel with your question.
- **Existing thread**: Reply in the thread and mention `@mintlify` with a follow-up question.

Example questions:
- "Which pages mention the API rate limit?"
- "How do I set up authentication?"
- "How is our navigation structured?"

## Update documentation

Use the agent to update your documentation with a new request or in an existing thread.

- **New request**: Send a direct message to the agent or mention `@mintlify` in a channel with instructions on what to update.
- **Existing thread**: Reply in the thread and mention `@mintlify` with instructions on what to update.
- **With attachments**: Upload images, diagrams, code files, or other documents with your message. The agent automatically processes and includes them in your documentation. In a thread, the agent has access to images and files shared in earlier messages, so you can reference them in follow-up requests without reuploading.

The agent reads the context of the request or thread and creates a pull request in your connected repository with the updates.

## Reference other repositories

The agent can read source code from any repository connected through the [GitHub app](/deploy/github) or [GitLab integration](/deploy/gitlab), even if it isn't your documentation repository. This lets the agent build deeper context to guide documentation updates.

When you mention another repository in your request, the agent clones it on demand and inspects the relevant files before drafting changes.

Example prompts:

- "Update the authentication guide based on the changes in `acme/api-server/src/auth.ts`."
- "Document the new endpoints added in `acme/backend#1234`."
- "What repositories do you have access to?"

The agent treats cloned repositories as read-only. It uses them for context, but always opens pull requests against your documentation repository.

## Track progress in real time

When the agent is making changes to your documentation, it provides live feedback in the Slack thread.

- **Status updates**: A live-updating message shows what the agent is doing, such as how many files it has searched, read, and edited.
- **Task progress**: When the agent breaks your request into multiple tasks, it displays a checklist so you can track progress on each one.
- **Questions**: If the agent needs more information, it presents options for you to select from or reply in the thread with a custom answer.
- **Permission requests**: Before the agent runs a third-party action that writes data, such as sending an email or creating a ticket, it asks you to approve or deny the action. The permission request is only visible to the person who triggered the request. Click **Approve** to let the agent proceed or **Deny** to cancel the action.
- **Interruptions**: If you send a follow-up message while the agent is still working, it stops the current task and starts on the new one.
- **Completion**: When the agent finishes, it posts a summary with a link to the pull request and a link to open the changes in the web editor.

## Roles and permissions

The agent's capabilities in Slack match users' [roles](/dashboard/roles).

- **Admins and editors**: Can ask questions and make documentation changes. The agent has access to file editing and pull request tools.
- **Viewers**: Can ask questions only. The agent runs in read-only mode for Mintlify tools and third-party integrations.

To change a teammate's permissions, update their role on the [Members](https://app.mintlify.com/settings/organization/members) page of your dashboard.

## Best practices

- **Be specific**: Tell the agent exactly what you want to know or what you want changed and where.
- **Add context**: If a thread doesn't contain all the necessary information, include additional details in your message to the agent.
- **Review carefully**: You should always review pull requests that the agent creates before merging them.