# Slack Tools Setup

Set up the Slack Tools connector to enable automated Slack operations from runbooks

The Slack Tools connector provides authentication for all Slack-based runbook tools. Set it up once, and every Slack tool will use the connector's credentials automatically.

## Setup Process

1. **Open the Slack integration page**

   In the Risotto dashboard, go to **Settings → Integrations** and click the **Slack** card. The **Tools app** card ("Authenticates automation tools.") gives your automation tools their own authentication, separate from the **Chat app** card that handles ticket conversations. Click **Connect** on the **Tools app** card.

   *Product example: Slack's integration page, with the Chat app connected and Connect on the Tools app card.*

2. **Configure your bot and download the manifest**

   A **Connect Slack for Tools** dialog opens. In the required **Bot Name** field, enter a name for your Slack app (it defaults to "Risotto Automations"). This is the display name that will appear in Slack when the bot performs actions.

   If you need the org-wide (Enterprise Grid) capabilities, check **Install across the entire Slack organization** (see [Enterprise Grid](#enterprise-grid) below). Leave it unchecked for a normal per-workspace install. Then click **Download Manifest & Continue** to download the pre-configured app manifest.

   *Product example: The Connect Slack for Tools dialog, with the bot name and Download Manifest & Continue.*

   > **Tip:** Name your Slack app something that includes your Risotto agent name and its
   > action, like "Risotto Automations" or "IT Assist Tools". Consider using the
   > same icon and color scheme as your main Risotto agent.

   > **Note:** A Risotto organization has one Slack Tools connector. Every Slack tool and
   > automation posts as this app, with the same name and icon. You cannot set
   > a different name or icon for each runbook or automation. To post as a
   > different Slack app from one tool, use a [per-tool token
   > override](#per-tool-token-override).

3. **Create a Slack app from the manifest**

   Go to [api.slack.com/apps](https://api.slack.com/apps), click **Create New App**, and select **From an app manifest**. Choose your workspace and paste the downloaded manifest.

   After creating the app, open **Settings → Basic Information** in the left sidebar of your app's page. The **App Credentials** section lists the values you need: **App ID**, **Client ID**, **Client Secret**, and **Signing Secret**. The Client Secret and Signing Secret are masked; click **Show** next to each to reveal it. You don't need the **Verification Token**, which Slack has deprecated.

4. **Enter credentials and authorize**

   Back in Risotto, the dialog now shows **Slack App Credentials**: the form, with an **Instructions** pane beside it that repeats the steps in Slack. On a narrow screen, click **Instructions** to show the steps. Enter the four required credentials from the previous step: **App ID**, **Client ID**, **Client Secret**, and **Signing Secret**. The two secret fields are masked, with an eye icon to reveal what you've typed.

   > **Note:** Be sure to click **Show** to display the Client Secret in Slack before
   > copying it.

   Click **Save & Authorize** to complete the connection. Use **Back** to return to the bot name step if needed. After you authorize the app, Risotto opens the Slack integration page and shows the message **Tools app connected successfully**.

   *Product example: The Slack App Credentials dialog with the four credentials entered and Save & Authorize.*

## Enterprise Grid

If your Slack organization is on Enterprise Grid and you want tools to act on channels the bot has not joined, check **Install across the entire Slack organization** during setup. This adds Slack's admin scopes to the manifest and the authorization request, which enable advanced operations:

- `admin.conversations:read` and `admin.conversations:write`: rename and archive channels (including private channels), convert channel privacy, and invite people to channels. These work in channels the bot isn't a member of.
- `admin.roles:write` — promote users to Channel Manager
- `conversations.connect:manage` — approve and deny Slack Connect invite requests (see [Slack Connect Invite Approval](https://www.tryrisotto.com/docs/integrations/tools/slack/slack-connect-invite-approval))

An org-wide install also subscribes the app to the `shared_channel_invite_requested` event. The manifest sends it to a request URL that is unique to your Risotto organization.

The choice applies to the setup attempt you are making and isn't remembered: reconnecting later starts with the box unchecked, so check it again if you still want an org-wide install.

> **Warning:** An app that requests these admin scopes must be installed at the
> **organization level** by an **org owner**. Slack refuses to install it into a
> single workspace, so leave the box unchecked unless your Slack organization is
> on Enterprise Grid and an org owner is doing the install. The wizard's
> manifest and authorization link target the organization for you.

### Add the app to your workspaces

Slack does not add an org-level app to any workspace by itself. After the org-wide install, add the app you created for the connector to every workspace where the tools act. Without this step, a workspace-scoped action fails, for example a user group update or a channel join. The tool reports *"The Slack app does not have access to that workspace."* Actions that use Slack's admin API, for example a Channel Manager promotion, work without this step, so one tool can succeed while another fails.

1. **Open the installed apps**

   In Slack, click your organization name, then **Tools & settings > Organization settings**. In the left sidebar, click **Integrations**, then the **Installed apps** tab.

2. **Add the app to workspaces**

   Find the app you created for the connector, click the three dots to its right, and select **Add to more workspaces**. Check each workspace where the tools act, click **Next**, check **I'm ready to add this app**, and click **Add App**.

You do not need to reconnect the connector in Risotto afterwards. The org-level token covers every workspace you add.

## Connector Scopes

The connector stores both a bot token and a user token to cover all Slack tool operations.

### Bot Scopes

- `channels:join`
- `channels:manage`
- `channels:read`
- `channels:write.invites`
- `chat:write`
- `conversations.connect:write`
- `groups:read`
- `groups:write`
- `groups:write.invites`
- `im:write`
- `pins:write`
- `users:read`
- `users:read.email`

### User Scopes

- `channels:write`
- `usergroups:read`
- `usergroups:write`
- `users:read`
- `users:read.email`

### Enterprise Grid (Optional)

These scopes are added when **Install across the entire Slack organization** is checked:

- `admin.conversations:read`
- `admin.conversations:write`
- `admin.roles:write`
- `conversations.connect:manage` (bot scope)

## Reconnecting the connector

Risotto adds scopes as new Slack tools ship. When your app does not grant a scope a tool needs, the **Tools app** card on the Slack integration page shows *"Slack does not grant these permissions yet: ..."*, and its status reads **Error** instead of **Connected**. When an automation trigger needs an event your app does not send, the card shows *"Slack does not send automation trigger events to Risotto yet."* When the connector is connected, the card's status menu has **Reconnect...**. Use it to add scopes or to replace a revoked token without entering your app's credentials again.

1. **Click Reconnect**

   Go to **Settings > Integrations > Slack**. On the **Tools app** card, click the status (**Error** or **Connected**), then **Reconnect...**. If no scope or event subscription is missing, Risotto sends you straight to Slack to authorize again, and you are done. Otherwise, the **Reconnect Slack tools** dialog opens.

2. **Copy the missing scopes**

   Click the copy button on the scopes snippet. The snippet holds only the scopes your app lacks, in the `oauth_config.scopes` shape of the manifest, split into `bot` and `user` lists.

   If your app also lacks an event subscription that an automation trigger needs, the dialog shows an `event_subscriptions` block too. Copy it as well.

3. **Update the app in Slack**

   Click **your app's manifest editor** to open the app in Slack. Add the copied scopes to the `oauth_config.scopes` lists the app already has, and keep the existing scopes. If you copied an `event_subscriptions` block, add it under `settings`; if the app already has `bot_events`, add the events to that list. Click **Save Changes**, and click **Verify** if Slack asks you to verify the request URL. If Slack asks you to reinstall the app, reinstall it to your workspace, or to your organization for an org-wide install. The **Install App** link opens the current install.

4. **Authorize**

   Back in the dialog, click **Authorize**. Slack asks you to approve the widened scopes, then Risotto stores the new tokens and checks the granted scopes.

   *Product example: The Reconnect Slack tools dialog with the missing scopes to copy and Authorize.*

Risotto keeps the install type of the existing token, so an org-wide install stays org-wide; there is no checkbox to set again. Editing the manifest and reinstalling from Slack alone is not enough: Risotto receives the new tokens only when the authorization starts from the dashboard. The old token stays in place until the new authorization succeeds, so an abandoned attempt changes nothing.

## Per-Tool Token Override

If you need a specific tool to use different credentials — for example, a tool operating in a separate workspace — you can provide a per-tool bot token or user token in that tool's configuration. Per-tool tokens take precedence over the connector.

> **Note:** When using a per-tool token override, you must also set the **Team ID** in the
> tool configuration.

## Migrating from Manual Token Setup

If you previously configured Slack tools with manually created tokens, those tokens continue to work. To migrate to the connector:

1. Complete the setup process above
2. Remove the per-tool token overrides from your tool configurations
3. The connector credentials take effect automatically when no per-tool override is present

> **Note:** Slack tools created before April 15, 2026 use the first version of the tool,
> which never uses the connector, even with the token override removed. Its tool
> page shows **New Version Available** and an **Upgrade** button. The upgrade
> keeps the existing **Bot Token** and **Team ID**, so clear them before you
> finish it. You can also create a new Slack tool with no token and use it in
> your runbooks instead.

Source: https://www.tryrisotto.com/docs/integrations/tools/slack/setup
