> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openhands.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack Channel Monitor

> Watch a Slack channel and trigger agent actions on messages.

Use the Slack Channel Monitor when you want Agent Canvas to watch a Slack channel and trigger an OpenHands agent when a message matches your instructions.

Common examples include:

* Responding when someone mentions a support keyword
* Turning bug reports into GitHub issues
* Summarizing incidents from an alerts channel
* Running a repository task from a Slack request

## Prerequisites

Before you start, make sure you have:

* Agent Canvas installed and running
* An LLM configured for the backend that will run the automation
* Permission to create and install a Slack app in your workspace
* Access to install MCP servers and save secrets in Agent Canvas

If you are new to Agent Canvas, start with [Install](/openhands/usage/agent-canvas/setup) and [First-Time Setup](/openhands/usage/agent-canvas/first-time-setup).

## Create the Slack App

1. Go to the [Slack API dashboard](https://api.slack.com/apps).
2. Click `Create New App`.
3. Select `From scratch`.
4. Enter an app name, such as `OpenHands`.
5. Choose the workspace where you want to install the bot.
6. Click `Create App`.

## Add Bot Token Scopes

Before Slack gives you a bot token, you need to define what the bot is allowed to do.

1. In the Slack app settings, open `OAuth & Permissions`.
2. Scroll to `Scopes`.
3. Under `Bot Token Scopes`, click `Add an OAuth Scope`.
4. Add the scopes required by the Slack MCP server and your monitor.

For a channel monitor, add these bot token scopes:

| Scope               | Purpose                                                                    |
| ------------------- | -------------------------------------------------------------------------- |
| `app_mentions:read` | View messages that directly mention the app in conversations it belongs to |
| `channels:read`     | List and read public channel metadata                                      |
| `channels:history`  | Read messages from public channels                                         |
| `chat:write`        | Send messages as the app                                                   |
| `emoji:read`        | View custom emoji in the workspace                                         |
| `groups:history`    | Read messages from private channels the app has been added to              |
| `reactions:read`    | View emoji reactions and associated message content                        |
| `reactions:write`   | Add and edit emoji reactions                                               |
| `users:read`        | Resolve Slack users and profiles                                           |

<Note>
  Slack may require you to reinstall the app after changing scopes.
</Note>

## Install the App and Copy the Bot Token

1. Stay on the `OAuth & Permissions` page.
2. Click `Install to Workspace`.
3. Review the requested permissions.
4. Click `Allow`.
5. Copy the `Bot User OAuth Token` from the `OAuth Tokens` section.

## Invite the Bot to Channels

The bot does not automatically join channels.

Invite it to every channel you want the automation to monitor. The Agent Canvas backend can only watch channels the bot can access.

## Find Your Slack Workspace ID

The Slack MCP server also needs your workspace ID.

You can find it from your Slack URL or workspace settings. See Slack's guide to [locating your Slack URL or ID](https://slack.com/help/articles/221769328-Locate-your-Slack-URL-or-ID).

## Add the Slack MCP Server

The Slack MCP server gives the agent tools for reading Slack channel activity and posting responses.

1. In Agent Canvas, check the backend switcher in the bottom-left corner.
2. Make sure the active backend is the backend where you want the Slack monitor to run.
3. Open `Customize`.
4. Open `MCP Servers`.
5. Select `Slack` from the MCP library.
6. Paste the bot token.
7. Enter your Slack workspace ID.
8. Make sure the secret-creation toggle is on so Agent Canvas creates the bot token secret automatically when you save the MCP server configuration.
9. Save the MCP server configuration.

## Start the Slack Channel Monitor Workflow

1. Open `Automate` in the left navigation.
2. Find `Start from a proven workflow`.
3. Choose the Slack channel monitor workflow.
4. Agent Canvas opens a new conversation with a prefilled setup prompt.
5. Send the prompt as-is, or edit it first if you already know what you want.

After you send the prompt, the agent starts a setup conversation. It uses the preconfigured skills and Slack access to interview you, clarify the channel monitor, and create the automation.

## Customize the Monitor

You do not need to know every detail before sending the prefilled prompt. The agent will ask follow-up questions to clarify:

* The Slack channel or channels to monitor
* The message pattern, keyword, or mention that should trigger the agent
* What the agent should do when a message matches
* Whether the agent should reply in Slack
* Any GitHub repository or external service the agent should use

<Info>
  If you want the automation to watch for `@your-bot-name`, tell the agent to watch for Slack bot mentions as well as the trigger phrases you set. That way, it can respond when someone mentions the bot directly, not just when a specific keyword appears.
</Info>

You can edit the prefilled prompt before sending it if you want to provide any of those details up front.

For example, you can ask the tell the agent to configure the automation to watch an #alerts channel, summarize new incidents, and create a GitHub issue when a message includes a production error.

## Verify the Automation

After the automation is created:

1. Open `Automate`.
2. Confirm the new automation appears in the list.
3. Open the automation details and check that it is enabled.
4. Post a test message in a channel the bot has joined.
5. Confirm that the agent run appears and performs the action you requested.

## Related Guides

* [GitHub Repository Monitor](/openhands/usage/agent-canvas/prebuilt/github-repo-monitor)
* [Setup a Pre-built Automation](/openhands/usage/agent-canvas/prebuilt-automations)
* [Customize and Settings](/openhands/usage/agent-canvas/customize-and-settings)