Add the agent to Slack

Add the Mintlify agent to Slack to ask questions about your docs, create documentation updates from conversations, and capture team knowledge.

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

Connect your Slack workspace

1. Go to the Agent page in your dashboard.
2. In the “Agent settings” section, click Install Slack app.

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.

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.

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.

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.

Connect additional integrations from Slack

After you connect your Slack workspace, you can ask the agent in Slack to set up any third-party integration that it should use as context. The agent uses Composio to support a broad catalog of third-party services, including issue trackers, knowledge bases, CRMs, and developer tools.

You must configure GitHub and GitLab through Mintlify, not Composio. Use the GitHub app or GitLab integration to control which repositories the agent can access.

To add a new integration from Slack:

1. In a direct message or a thread that mentions @mintlify, ask the agent to set up the integration. For example:
   • “Connect Jira so you can read tickets.”
   • “Install the HubSpot integration.”
   • “Set up the Linear integration.”
2. The agent replies with an authorization link.
3. Click the link, sign in to the third-party service, and approve the requested permissions. After you authorize, your browser displays a confirmation page indicating that the connection is complete.
4. Return to Slack. The agent confirms the connection and can immediately use the integration as context for future requests.

Integrations that you connect from Slack apply to individual Slack users, so each teammate sets up their own connections and the agent uses the connections of whoever sent the message. If a Slack user has not connected a service, the agent falls back to the organization-level integrations installed from the Agent page in the dashboard.

To remove or reauthorize an organization-level integration, use the Agent settings section of the Agent page.

For the full list of supported services, see the Composio toolkits catalog.

Expired or revoked connections

Mintlify keeps the status of your connected services in sync with Composio. A connection is disconnected when:

• The third-party provider expires or revokes the credentials.
• The provider marks the connection as inactive.
• You delete the connection.

If a connection is no longer active, the next time you ask the agent to use that service it replies with an authorization link. Click the link, reauthorize the service, and the agent resumes the connection.

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 and images shared 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 that has the Mintlify GitHub App installed, 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.

• 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 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.