# Manage Slack Channel Members

Invite, remove, or promote users in Slack channels with automatic bot management

Manages Slack channel membership by inviting users, removing users, or promoting users to Channel Manager. This tool automatically handles bot permissions and provides detailed error messages for troubleshooting.

## Authentication

This tool authenticates through the Slack Tools connector. Follow the [Slack Tools Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup) guide to configure it.

## Setup Requirements

### Basic Operations (All Slack Plans)

For inviting and removing members, no special setup is required beyond having the [Slack Tools connector](https://www.tryrisotto.com/docs/integrations/tools/slack/setup) configured.

### Advanced Operations (Enterprise Grid Only)

> **Warning:** Promoting users to Channel Manager requires **Slack Enterprise Grid** and the
> **Install across the entire Slack organization** option (see [Enterprise
> Grid](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#enterprise-grid)) chosen when setting up
> the Slack Tools connector.

## Configuration Options

When configuring this tool in a runbook, you can set:

- **Operation** - Action to perform: INVITE, REMOVE, or PROMOTE
- **User Email** - Email of the user to manage
- **Channel ID** - Slack channel ID (e.g., 'C1234567890')
- **Channel Name** - Channel name (used if Channel ID is not provided)
- **Role** - For INVITE/PROMOTE operations: MEMBER or MANAGER
- **Bot Token** *(Optional override)* - Per-tool bot token. Takes precedence over the Slack Tools connector.
- **Team ID** *(Optional)* - Required only when using a per-tool bot token override

## Features

### Automatic Bot Management

The tool automatically handles bot membership:

- **Inviting users**: When the Slack Tools connector was set up with **Install across the entire Slack organization** (Enterprise Grid), the tool sends the invite through Slack's admin API first. The admin API does not need the bot in the channel, so it can add a user to a private channel that the bot was never invited to. If the admin API refuses (for example, the token that installed the app no longer belongs to an Org Admin), the tool uses the bot: the bot joins the channel, invites the user, and then leaves. Without an organization-wide install, the tool always uses the bot.
- **Invite messages**: An invite sent through the admin API adds the user without a "joined" message from the bot in the channel. An invite sent by the bot shows the bot and the user joining together.
- **Removing users**: Bot automatically joins the channel if needed, then leaves after removal
- **Promoting users**: Uses org-level admin API without channel membership requirements

### Idempotent Operations

Operations are designed to be safe to run multiple times:

- Inviting a user already in the channel returns "User is already in channel" and changes nothing
- Inviting a user who is not a member of the channel's workspace returns a message that says so
- The tool handles channel lookup by name or ID automatically

### Smart Channel Resolution

You can specify channels by:

- **Channel ID** (e.g., `C1234567890`) - Fastest and most reliable
- **Channel Name** (e.g., `engineering-team`) - Automatically searches all channels

> **Tip:** Using Channel ID is recommended for better performance in workspaces with many
> channels.

### Comprehensive Error Handling

The tool provides clear, actionable error messages:

- Permission issues with links to workspace settings
- Missing scope indicators
- Enterprise Grid requirements
- User and channel not found errors

## Troubleshooting

### Common Issues

#### Bot is not a member of the channel and cannot invite users

**Cause**: The bot lacks permission to invite users to the channel

**Solution**:

1. Invite the app that the tool acts as to the channel. When the Slack Tools connector is set up, that is the connector's app: the **Bot Name** you chose during [setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup) ("Risotto Automations" by default). Your main Risotto app is a different app, so inviting it does not help. Without the connector, the tool falls back to your main Risotto app.
2. If Slack says the connector's app is not in the workspace, the connector was installed at the organization level and not yet added to this workspace. See [Add the app to your workspaces](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#add-the-app-to-your-workspaces).
3. Grant the bot appropriate channel permissions
4. Ensure the bot has `channels:manage` or `groups:write` scope

Slack's invite list can show two Risotto entries: your main Risotto app and the Slack Tools connector's app. Slack tools use the connector's app.

#### Bot token is missing required scope

**Cause**: The bot token doesn't have the necessary permissions

**Solution**:

- For basic operations: Ensure `channels:manage`, `groups:write`, and `users:read.email` scopes
- For promoting to Channel Manager: Add `admin.roles:write` scope
- Reconfigure the [Slack Tools connector](https://www.tryrisotto.com/docs/integrations/tools/slack/setup) if using default credentials
- If the tool has its own **Bot Token**, Risotto uses that token, not the connector. Add the scopes to that token, or move the tool to the connector as described in [Migrating from Manual Token Setup](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#migrating-from-manual-token-setup)

#### Cannot remove users from the #general channel

**Cause**: Slack prevents removing users from #general by design

**Solution**:
This is a Slack limitation that cannot be overridden. Users must remain in #general.

#### Workspace setting prevents this removal

**Cause**: Slack workspace policy restricts removing users from public channels

**Solution**:

1. Go to your workspace settings: `https://[workspace].slack.com/admin/permissions/account-types`
2. Find the "Remove users from public channels" permission
3. Adjust the policy to allow the bot or admin to remove users

#### This workspace does not have Enterprise Grid enabled

**Cause**: Attempting to promote a Channel Manager without Enterprise Grid

**Solution**:

- The PROMOTE operation requires Enterprise Grid
- Use INVITE with role MEMBER for standard channel membership
- Consider upgrading to Enterprise Grid for advanced role management
- Contact your Slack account manager about Enterprise Grid features

#### Bot token does not have admin privileges

**Cause**: Org-level token required for admin operations

**Solution**:

1. Choose **Install across the entire Slack organization** when setting up the Slack Tools connector (see [Enterprise Grid](https://www.tryrisotto.com/docs/integrations/tools/slack/setup#enterprise-grid))
2. Ensure the app is installed at the org level
3. If using a per-tool token override, add the `admin.roles:write` scope and specify the `team_id`

#### Invite fails with 'the admin API also refused'

**Cause**: With an org-wide Enterprise Grid install, Risotto tries the Slack admin API first. Slack refused that invite, and then the bot could not join the channel to invite the user. The message shows the bot's error first. The code after "the admin API also refused:" is Slack's reason for the admin refusal, for example `not_an_admin`.

**Solution**:

1. Read both errors. The admin code tells you why the admin invite failed, and the first part tells you why the bot invite failed.
2. To make the bot invite work, invite the connector's app to the channel (see "Bot is not a member of the channel and cannot invite users" above).

### Permission Requirements

**For Basic Operations (INVITE, REMOVE):**

- Bot must have access to the channel (automatically managed)
- Required scopes: `channels:manage`, `groups:write`, `users:read.email`
- Works on all Slack plans

**For Channel Manager Promotion (PROMOTE):**

- Requires Slack Enterprise Grid
- App must be installed at org level
- Required scope: `admin.roles:write`
- Bot needs admin privileges in the workspace

## Additional Resources

- [Slack Admin API: Roles](https://api.slack.com/methods/admin.roles.addAssignments)
- [Understanding Channel Managers](https://slack.com/help/articles/8328303095443-Understand-Channel-Managers-in-Slack)
- [Slack App Management](https://api.slack.com/apps)
- [Enterprise Grid Overview](https://slack.com/help/categories/360000049043)

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