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

# Slack integration

Connect a Slack workspace to give Agents and Flow prompt steps tools that send messages, read channels, and ask people questions in Slack. Slack isn't available as a standalone Flow step.

## Before you begin

Make sure that you can create and install a Slack app in your Slack workspace.

## Connect a Slack workspace

The Slack tools use a Slack workspace that is installed in your Runtype organization. To install one from the dashboard, set up a Slack Surface. The setup wizard generates the Slack app manifest with the scopes that the tools need, installs the app, and stores the bot token for you. For the steps, see [Setting up a Slack Surface](/user-guide/products-surfaces/setting-up-a-slack-surface).

After the install finishes, the same workspace powers both the Surface and the Slack tools. You don't need a separate bot token.

> **Note**
>
> If no Slack workspace is installed, selecting **Slack** in the tool picker opens a **Bot Token**
> form. Saving that form returns an error, because Slack credentials can't be saved there. Install
> the workspace through a Slack Surface or the API instead.

### Connect with the API

To install a workspace without a Surface, send a `POST` request to `/v1/integrations/slack/install` with your Slack app's team ID, bot token, and signing secret. The bot token starts with `xoxb-`.

**`cURL`**

```bash title="cURL"
curl -X POST https://api.runtype.com/v1/integrations/slack/install \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": "YOUR_TEAM_ID",
    "botToken": "xoxb-YOUR_BOT_TOKEN",
    "signingSecret": "YOUR_SIGNING_SECRET"
  }'
```

Replace the following:

* `YOUR_API_KEY`: your Runtype API key.
* `YOUR_TEAM_ID`: the ID of your Slack workspace.
* `YOUR_BOT_TOKEN`: the part after `xoxb-` of the **Bot User OAuth Token** from your Slack app's **OAuth & Permissions** page.
* `YOUR_SIGNING_SECRET`: the **Signing Secret** from your Slack app's **Basic Information** page.

The Slack app needs the bot scopes that the tools call, such as `chat:write`, `channels:read`, `channels:history`, `reactions:write`, and `users:read`. The response returns the workspace's `integrationId`. For every field, see [Install Slack integration](/api-reference/runtype-api/integrations/install-slack-integration).

## Add Slack tools

To add Slack tools to an Agent, follow these steps:

1. Open the Agent that you want to configure.
2. In the tools bar, click **Add tool**. The tool picker opens.
3. Select **Slack**, then select the Slack tools that the Agent needs.
4. Close the tool picker and save the Agent.

In a Flow, add the tools from a prompt step's tools panel. For more information, see [Using prompt steps](/user-guide/flows/using-prompt-steps).

To confirm the connection, run the Agent with a prompt that asks it to post a short message to a test channel. The message appears in Slack.

## Available tools

The following table lists the Slack tools. Through the API, name a tool as `builtin:slack:` followed by the tool name, for example `builtin:slack:send_message`.

| Tool                  | What it does                                                                                             | Key parameters                                                  |
| --------------------- | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
| `send_message`        | Sends a message to a channel or user, as Slack markdown or Block Kit blocks.                             | `channel`, `text`, `thread_ts`, `reply_mode`, `blocks`          |
| `send_rich_message`   | Sends an informational Block Kit message that doesn't wait for a click.                                  | `channel`, `text`, `blocks`                                     |
| `list_channels`       | Lists public channels in the workspace.                                                                  | `limit` (1 to 1000, default 100), `cursor`                      |
| `get_channel_history` | Reads message history from a channel.                                                                    | `channel`, `limit` (1 to 1000, default 100), `oldest`, `latest` |
| `get_thread_replies`  | Reads the replies in a thread, including the parent message.                                             | `channel`, `thread_ts`, `limit` (1 to 200, default 50)          |
| `add_reaction`        | Adds an emoji reaction to a message.                                                                     | `channel`, `timestamp`, `name`                                  |
| `get_user_info`       | Looks up a Slack user.                                                                                   | `user`                                                          |
| `prompt_user`         | Asks the user to choose from up to five labeled buttons, for example to approve an Agent's decision.     | `text`, `options`                                               |
| `select_from_list`    | Asks the user to choose from a dropdown of up to 100 options. Set `multi` to allow more than one choice. | `text`, `options`, `multi`                                      |

When a Slack Surface starts the run, `channel` and `thread_ts` default to the current conversation. The `reply_mode` parameter of `send_message` and `send_rich_message` sets where the message goes: `thread` replies in the current thread, `channel` posts at the top level, and `broadcast` replies in the thread and also posts to the channel. The Slack Surface's **Allowed Reply Modes** setting controls which modes the tools can use, and its **Default Reply Mode** applies when a call omits `reply_mode`. By default, only `thread` is allowed.

Outside a Slack Surface run, only `thread` is allowed. A call without `thread_ts` then posts at the top level of the channel.

`prompt_user` and `select_from_list` work only in a run that a Slack Surface starts. From any other run, such as an API call or a Schedule, they fail with an error that says they require a messaging conversation.

If Slack rejects the `blocks` of a message, the tool call fails with guidance so that the Agent can fix the blocks and retry. Runtype doesn't post the message as plain text instead.

## Format messages

Use Slack's markdown syntax in the `text` parameter. The following snippet shows common formats:

**`Slack markdown`**

```plaintext title="Slack markdown"
*Bold text*
_Italic text_
~Strikethrough~
`Code`
> Quote

<https://example.com|Link text>
```

## Use more than one workspace

If your organization has one Slack workspace installed, the Slack tools use it automatically. In a run that a Slack Surface starts, the tools use that Surface's workspace unless a tool names another one. If your organization has more than one workspace, any other run needs each Slack tool to name its workspace. Otherwise the call fails with an error that says multiple Slack workspaces are installed.

To choose a workspace through the API, add an entry for the tool to the Agent's `tools.toolConfigs`, keyed by tool ID, and set its `integrationId` to the workspace's integration ID. Optional: Set `defaultChannelId` to the channel ID that the tool uses when a call omits `channel`. To use two workspaces in one Agent, add the tool once for each workspace with an instance suffix, such as `builtin:slack:send_message#support` and `builtin:slack:send_message#sales`, and give each ID its own `toolConfigs` entry.

## Rotate credentials

To replace the bot token, signing secret, or app ID of an installed workspace, send a `POST` request to `/v1/integrations/slack/rotate-credentials` with the workspace's `integrationId` and only the values that changed. The request fails with a `409` status if the new bot token belongs to a different Slack workspace. For a Surface install, you can also rotate the credentials from the Surface's **Reconfigure Slack credentials** panel.

## Troubleshoot

The following table lists common Slack tool errors:

| Error                                                                            | Cause                                                                 | Fix                                                                                                                     |
| -------------------------------------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `not_in_channel`                                                                 | The bot isn't a member of the channel.                                | In the channel, run `/invite @YOUR_BOT_NAME`, where `YOUR_BOT_NAME` is your Slack app's bot name.                       |
| No Slack workspace is available for this tool                                    | No Slack workspace is installed in your organization.                 | Set up a Slack Surface or install the workspace with the API.                                                           |
| The Slack integration is installed but its credentials are incomplete or revoked | The bot token or signing secret is missing or revoked.                | Rotate the credentials, or reinstall the Slack app.                                                                     |
| Multiple Slack workspaces are installed                                          | More than one workspace is installed and the tool doesn't name one.   | Set `integrationId` on the tool. For more information, see [Use more than one workspace](#use-more-than-one-workspace). |
| Requires a messaging conversation                                                | `prompt_user` or `select_from_list` ran outside a Slack conversation. | Call these tools only in a run that a Slack Surface starts.                                                             |

## Next steps

Continue with these guides:

* [Agent tools](/user-guide/agents/agent-tools): add and configure tools on an Agent.
* [Setting up a Slack Surface](/user-guide/products-surfaces/setting-up-a-slack-surface): install a Slack workspace and route Slack messages to a Product.
* [Integrations API reference](/api-reference/runtype-api/integrations/list-integrations): every Integrations endpoint and field.