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.

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

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

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.

Add Slack tools

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

Open the Agent that you want to configure.
In the tools bar, click Add tool. The tool picker opens.
Select Slack, then select the Slack tools that the Agent needs.
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.

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

*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.
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: add and configure tools on an Agent.
Setting up a Slack Surface: install a Slack workspace and route Slack messages to a Product.
Integrations API reference: every Integrations endpoint and field.