> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.astropods.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.astropods.com/_mcp/server.

# Connect an agent to Slack

Connect your agent to Slack so people can talk to it where they already work. Once connected, the agent appears in your Slack workspace as a bot. Users message it directly or mention it in a channel.

Astropods does this with the `slack` adapter, which relays each message between Slack and your agent over the [Messaging SDK](/messaging-sdk). You enable it in the agent's configuration, or at deploy time with `--adapter slack`.

Watch the video for an overview, or follow the procedure below.

## Before you start

To complete this guide, you need the following:

* An agent that is already deployed and live. See [Deploy an agent](/deploy-agent) if you haven't deployed one.
* A Slack workspace where you can create apps. You add the bot to a channel there.
* Access to your agent's configuration in Astropods. You paste the Slack tokens there.

## Create and configure the Slack app

Create the app in the Slack workspace where your target channel lives. Set the app's scopes, Socket Mode, and event subscription with a manifest. Then create an app-level token and install the app.

#### Create the app from a manifest

1. Go to Slack's [Your Apps](https://api.slack.com/apps) page and click **Create New App**.
2. Under **From scratch**, select **Paste a manifest** and click **Continue**. Click the **YAML** tab, then replace the default manifest with the manifest below.

```yaml
display_information:
  name: My Astropods agent
features:
  bot_user:
    display_name: My Astropods agent
oauth_config:
  scopes:
    bot:
      - chat:write
      - app_mentions:read
      - files:read
      - files:write
settings:
  socket_mode_enabled: true
  event_subscriptions:
    bot_events:
      - app_mention
```

3. Select a workspace, then click **Next**.
4. Review the summary and click **Create**.

The manifest grants these [bot scopes](https://docs.slack.dev/reference/scopes): `chat:write` sends messages, `app_mentions:read` detects @mentions, and `files:read` and `files:write` let your agent read files users attach and send files back. You can remove the two file scopes if your agent doesn't handle files. See [Files in Slack](/messaging-sdk/files-in-chat#files-in-slack) to learn more.

The manifest also turns on Slack's [Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode), which lets your agent communicate with Slack without a public URL, and subscribes the app to the `app_mention` bot event. Slack delivers no events to your app without that subscription, so a missing one is the most common reason the integration fails with no error.

#### Create an app-level token

After you create the app, Slack opens its **Basic Information** page. Scroll to **App-Level Tokens** and click **Generate Token and Scopes**. Name the token, add the `connections:write` scope, and click **Generate**. Copy the token, which you need later. It starts with `xapp-`. Click **Done** to close the dialog.

#### Install the app

1. In the sidebar, click **Install App**.
2. Click **Install to** *your workspace*.
3. Review the permissions and click **Allow**.
4. On the **Installed App Settings** page, copy the **Bot User OAuth Token**. It starts with `xoxb-`.

If your workspace requires approval for new apps, click **Request to Workspace Install** instead. The token appears on **Install App** after a workspace admin approves the request.

> **Note**
>
> If you add a scope or event after installing, you must reinstall the app for the changes to take effect.

## Connect the app to your agent

#### Add the tokens to your agent's configuration

1. In Astropods, click the **Agents** tab and select your agent.
2. In the sidebar, under **Configuration**, click **General**.
3. Under **Messaging interface**, click **Slack**.
4. Paste your **Slack App Token** and **Slack Bot Token** into the corresponding fields.
5. The optional fields below (**Actionable Reactions**, **Allowed Channel IDs**, **Observe Channel IDs**) can be left blank for an initial test. See [Configure bot behavior](#configure-bot-behavior) for what each one does.
6. Click **Redeploy** to apply the change. Astropods opens **Deployments**. Wait about a minute for the status to change from **Deploying** to **Active**.

#### Invite the bot to a channel and test

Installing the Slack app does not automatically add it to any channel. In the channel where you want to use the agent, type `/invite @` and the first letters of the bot's name, such as `/invite @my`. Select the bot from the list, then send the message.

Then mention the bot. Type `@`, select the bot from the list, and add a message:

```
@My Astropods agent are you there?
```

The agent replies in the thread.

## Configure bot behavior

The optional fields under **Messaging interface** control where and how the bot responds. Separate multiple values with commas. Leave a field blank to use its default.

| Field                    | Description                                                                                         |
| ------------------------ | --------------------------------------------------------------------------------------------------- |
| **Actionable Reactions** | Emoji names, without colons, that send a reaction to your agent. When blank, no reactions are sent. |
| **Allowed Channel IDs**  | Channel IDs the bot responds in. When blank, the bot responds everywhere it is added.               |
| **Observe Channel IDs**  | Channel IDs where every top-level message reaches your agent, not only mentions.                    |

### Set Slack variables from the CLI

Astropods stores the Slack settings as three variables. The agent configuration page sets them from its fields when you click **Redeploy**. To set them from the CLI, pass each one with `--var`. See [ast blueprint](/cli/blueprint) for the flags.

| Variable          | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `SLACK_BOT_TOKEN` | The bot token (`xoxb-…`). Required.                       |
| `SLACK_APP_TOKEN` | The app-level token (`xapp-…`) for Socket Mode. Required. |
| `SLACK_CONFIG`    | Optional bot behavior, as a JSON object.                  |

`SLACK_CONFIG` holds the optional fields as keys:

| Field                    | `SLACK_CONFIG` key     |
| ------------------------ | ---------------------- |
| **Actionable Reactions** | `actionable_reactions` |
| **Allowed Channel IDs**  | `allowed_channel_ids`  |
| **Observe Channel IDs**  | `observe_channel_ids`  |

For example, this command restricts the bot to one channel:

```bash
ast blueprint deploy my-agent --adapter slack \
  --var SLACK_BOT_TOKEN=@SLACK_BOT_TOKEN \
  --var SLACK_APP_TOKEN=@SLACK_APP_TOKEN \
  --var 'SLACK_CONFIG={"allowed_channel_ids":["C0123ABCDEF"]}'
```

Each `SLACK_CONFIG` value replaces the previous one, so a redeploy that sets it must include every field you want to keep. The value must be valid JSON. The deploy does not check it, and a malformed value stops both Slack and web chat from starting for that agent.

## Restrict the bot to channels

Once **Allowed Channel IDs** is set, the bot replies to a mention or thread reply in any other channel with a notice that the app is not enabled there, and your agent never receives it.

The channel list controls where the bot listens. Who can use the agent is a separate setting: [interface access](/access-control#who-can-talk-to-an-agent).

To find a channel ID in Slack, open the channel details. The ID is at the bottom of the **About** tab.

## Troubleshoot

If the agent doesn't reply, check in this order:

1. Event subscriptions are enabled in the Slack app (the most common miss).
2. The `app_mention` bot event is subscribed, and the app was reinstalled after adding it.
3. The bot was actually invited to the channel.
4. The agent configuration was redeployed after the tokens were added.

Astropods' agent monitoring page (**Agents > Monitor > Networking**) can help confirm whether a Slack event reached the agent at all. If no inbound Slack traffic appears after a mention, the issue is on the Slack side (events not enabled, bot not invited) rather than in the agent itself.

---

## Next steps

* [Deploy an agent](/deploy-agent): choose which adapters a deployment enables
* [Managing your agents](/managing-agents): inspect, update, and control a running agent
* [Monitor your agents](/monitor-agents): add tracing and metrics to a deployed agent