> ## Documentation Index
> Fetch the complete documentation index at: https://slackhive.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Slack App Setup

> Create and configure a Slack app for each agent.

Every SlackHive agent needs its own Slack app. The app is how your agent gets a Slack identity (`@handle`), connects to your workspace, and receives messages.

The good news: **you don't need to configure scopes or settings manually.** SlackHive generates a complete app manifest from the agent page - you just paste it into Slack and click a few buttons.

This page walks through that process in detail, and covers troubleshooting if something goes wrong.

## What you're creating

Each Slack app gives your agent:

* A **bot user** - the `@handle` your team @mentions in channels
* **Socket Mode** - a persistent connection that receives messages in real time (no webhooks needed, no public URL required)
* The right **OAuth scopes** - permissions to read messages, post replies, and add reactions

## Step 1: Generate the manifest

Open the agent's **Overview** tab, find the Slack connection card, and click **Manage Slack** or **Connect Slack**. Then click **View Slack Manifest**. SlackHive creates a JSON manifest pre-configured for your agent with the correct name, scopes, and Socket Mode settings.

Keep this manifest JSON ready - you'll paste it into Slack in the next step.

## Step 2: Create the Slack app

<Steps>
  <Step title="Open the Slack API console">
    Go to [api.slack.com/apps](https://api.slack.com/apps) in a new browser tab. Sign in with the Slack account that has permission to install apps in your workspace.
  </Step>

  <Step title="Start creating a new app">
    Click the **Create New App** button in the top right. A dialog will appear asking how you'd like to configure your app.
  </Step>

  <Step title="Choose From an app manifest">
    Select **From an app manifest** (not "From scratch"). This lets you paste the pre-configured manifest rather than setting everything up manually.
  </Step>

  <Step title="Select your workspace">
    Choose the Slack workspace where you want this agent to live. Click **Next**.
  </Step>

  <Step title="Paste the manifest">
    You'll see a text editor. Delete any existing content, then paste the manifest JSON from SlackHive. Click **Next**.
  </Step>

  <Step title="Review and create">
    Slack will show you a summary of the app settings. Click **Create** to finish. You'll land on the app's settings page.
  </Step>
</Steps>

## Step 3: Install to your workspace

Your app exists, but it's not yet installed in your workspace.

<Steps>
  <Step title="Go to OAuth & Permissions">
    In the left sidebar of the Slack app settings page, click **OAuth & Permissions**.
  </Step>

  <Step title="Install the app">
    Click the **Install to Workspace** button near the top of the page.
  </Step>

  <Step title="Approve the permissions">
    Slack shows you a list of what the app will be allowed to do. Review it and click **Allow**.
  </Step>
</Steps>

Your bot user (`@your-agent-name`) now exists in your workspace.

## Step 4: Collect your credentials

You need three values to connect the agent in SlackHive. Here's exactly where to find each one.

### Bot Token (`xoxb-...`)

1. Go to **OAuth & Permissions** in the left sidebar
2. Under **OAuth Tokens for Your Workspace**, find **Bot User OAuth Token**
3. Copy it - it starts with `xoxb-`

### App Token (`xapp-...`)

1. Go to **Basic Information** in the left sidebar
2. Scroll down to **App-Level Tokens**
3. Click **Generate Token and Scopes**
4. Give it a name (e.g. `socket-mode`)
5. Click **Add Scope** and select `connections:write`
6. Click **Generate**
7. Copy the token - it starts with `xapp-`

### Signing Secret

1. Still on **Basic Information**
2. Under **App Credentials**, find **Signing Secret**
3. Click **Show** to reveal it, then copy the hex string

## Step 5: Enter credentials in SlackHive

Go back to the agent's **Overview** tab in SlackHive, open the Slack connection card, and paste the required values:

| Field              | Value                                                                     |
| ------------------ | ------------------------------------------------------------------------- |
| **Bot Token**      | `xoxb-...`                                                                |
| **App Token**      | `xapp-...`                                                                |
| **Signing Secret** | Optional for Socket Mode. Only needed if you use Slack's HTTP Events API. |

Click **Save**. SlackHive stores the credentials and starts the agent's Slack listener.

## Required OAuth scopes

The generated manifest includes these bot token scopes. Here's what each one is for:

| Scope               | Why it's needed                                                       |
| ------------------- | --------------------------------------------------------------------- |
| `app_mentions:read` | Receive events when the bot is @mentioned in a channel                |
| `channels:history`  | Read messages in public channels (needed for thread context)          |
| `channels:read`     | List channels and get channel info                                    |
| `chat:write`        | Post messages and replies                                             |
| `groups:history`    | Read messages in private channels                                     |
| `groups:read`       | List and access private channels                                      |
| `im:history`        | Read direct messages                                                  |
| `im:read`           | Access DM channel info                                                |
| `im:write`          | Send direct messages                                                  |
| `mpim:history`      | Read group DMs                                                        |
| `reactions:write`   | Add emoji reactions (used for "thinking" indicators while processing) |
| `users:read`        | Look up user display names (for memory and context)                   |

## Troubleshooting

<Accordion title="Verification failed - connection refused">
  The most common cause is **Socket Mode not being enabled**.

  1. Go to your Slack app settings
  2. Click **Socket Mode** in the left sidebar
  3. Make sure the toggle is **On**
  4. Go back to SlackHive and try verifying again
</Accordion>

<Accordion title="Verification failed - invalid token">
  * Check that you pasted the **Bot Token** (starts with `xoxb-`) in the Bot Token field, not the App Token
  * Make sure there are no extra spaces before or after the token
  * If you recently regenerated the token, make sure you copied the new one
</Accordion>

<Accordion title="App Token scope error">
  The App Token must have the `connections:write` scope. If you created the token without adding this scope:

  1. Go to **Basic Information** → **App-Level Tokens**
  2. Click on your token name
  3. Add the `connections:write` scope
  4. Regenerate the token and copy the new value
</Accordion>

<Accordion title="Bot doesn't appear in workspace">
  If you can't find `@your-agent-name` in Slack after setup:

  1. Check that the app was installed: go to Slack app settings → **OAuth & Permissions** → the **Install to Workspace** button should show as already installed
  2. In Slack, type `@` in a message box and start typing the agent's name
  3. If it still doesn't appear, try reinstalling the app from **OAuth & Permissions**
</Accordion>

<Accordion title="Agent is Running but not responding">
  If the dashboard shows the agent as Running but it doesn't respond to @mentions:

  1. Make sure you've **invited the bot to the channel**: `/invite @your-agent-name`
  2. Check the **Logs** tab on the agent - it will show if messages are being received
  3. Verify the agent doesn't have channel restrictions set (Overview tab → Allowed Channels)
</Accordion>

## After setup

Once credentials are verified, the runner connects the agent to Slack automatically. The agent status changes to **Running** in the dashboard.

Invite the bot to a channel and start a conversation:

```
/invite @your-agent-name
@your-agent-name hello!
```

<Note>
  Each agent can only be installed in one Slack workspace. If you need agents in multiple workspaces, create separate Slack apps for each workspace and create separate agent entries in SlackHive.
</Note>

## Sign in with Slack (optional)

You can also use a Slack app to let your team log in to SlackHive with their Slack account — instead of a username and password.

This requires a **separate** Slack app (or the same one with additional OAuth configuration). You will need:

* **Client ID** and **Client Secret** from **Basic Information → App Credentials**
* The following **Redirect URL** added under **OAuth & Permissions → Redirect URLs**: `https://<your-slackhive-domain>/api/auth/slack/callback` (the path `/api/auth/slack/callback` is exact — only replace the domain)
* The `openid`, `email`, and `profile` scopes added under **OAuth & Permissions → User Token Scopes**

Once you have these, go to **Settings → Sign in with Slack** in SlackHive and enter the Client ID and Client Secret.

See [Settings & Users](/features/users#sign-in-with-slack) for the full configuration walkthrough and open vs invite-only login options.