> ## Documentation Index
> Fetch the complete documentation index at: https://squad.so/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Connect Slack
> Put your squad or one agent in Slack as an app that answers direct messages and @mentions in channels.
Each Slack app is a direct line to one agent. People on the app's list can send it direct messages. When channels are on, the app also answers when someone @mentions it in a channel that it was invited to. The app connects from your workspace computer with Slack's Socket Mode, so nothing needs a public URL.
This page is about the Slack app that you chat with. To give agents Slack as a tool for their work, connect Slack on **Integrations** > **Connected apps**. See [Connect apps](/docs/integrations). For how channels compare, see [Talk to your squad from Telegram, Discord, or Slack](/docs/channels).
## Before you start
* You need permission to create and install apps in your Slack workspace.
* Get your Slack member ID. In Slack, open your profile, click **⋯** (More), and click Copy member ID. The ID starts with U.
## Open the Slack screen
Use one of these paths:
* Open **Integrations**, click the **Channels** tab, and click **Slack**.
* Open **Settings** and click **Slack** under **CONNECTIONS**.
## Connect an app
Under **Connect an app**, in **Who is this app?**, select **The whole squad (the lead answers)** or one agent.
Click **Copy the @Squad manifest**. If you selected an agent, the button shows the agent's name instead of Squad. Slack uses this name for the app.
Open api.slack.com/apps and click Create New App.
Click From a manifest, pick your Slack workspace, and paste the manifest.
Create the app.
In the app's Basic Information page, under App-Level Tokens, generate a token with the `connections:write` scope.
On the Squad **Slack** screen, paste the token into **Generate the app-level token**. It starts with `xapp-`.
In the Slack app settings, open Install App and click Install to Workspace.
Copy the Bot User OAuth Token and paste it into **Install it to your Slack workspace**. It starts with `xoxb-`.
Under **Add yourself and connect**, type your Slack member ID.
Click **Connect @Squad**, or the button with the agent's name.
The manifest sets everything that the app needs, including Socket Mode and the permissions. It cannot set an icon. To give the app an icon, add one on the app's Basic Information page in Slack.
Copy both tokens from the same Slack app. Squad refuses tokens from two different apps.
### Check that it works
* The app shows as a card with **Online**.
* On the card, click **Verify connection**. A green message says that the app has every permission Squad needs.
* Send the app a direct message in Slack. The agent answers.
* In a channel, type `/invite @` followed by the app name, then @mention the app. The agent answers.
## Set up the app
Each app card has these controls:
| Control | What it does |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Answered by** | The agent that answers this app. The default is **The lead (default)**. |
| **Who can message it** | The Slack member IDs that can send the app direct messages. Everyone else is refused. |
| **Answer in channels** | On by default. The app answers when someone @mentions it in a channel that it was invited to. When off, the app answers direct messages only. |
| **Reply in a thread** | On by default. Answers go in a thread under the message that asked, in channels, groups, and direct messages. Each thread keeps its own working context. When off, answers post as new messages. |
| **Verify connection** | Checks the app's tokens and permissions, and tells you what is missing. |
| **Remove** | Removes the app. Click **Really remove? Messages stop immediately** to confirm. |
To add a person to **Who can message it**:
1. Ask the person for their Slack member ID.
2. Type the ID into the field under **Who can message it**.
3. Click **Add**.
A list can hold up to 50 people. See [Limits and defaults](/docs/limits-and-defaults).
## Known limits
* In channels, the app does not check its list. Anyone in a channel where the app was invited can @mention it and get an answer. If only the people on the list may use the app, turn off **Answer in channels**.
* The list cannot be empty. You can remove yourself when someone else is on the list. Squad does not keep you on a Slack list.
* The first app that you connect is the primary app. You cannot remove the primary app while other apps are connected. Remove the other apps first.
* The card has no field to replace a token. To use new tokens, see the troubleshooting entry below.
* If the card says that your squad's runtime limits the app to specific channels, the limit was set on your workspace computer. Ask your lead to change it.
## Troubleshooting
**The app receives messages but does not reply.**
Cause: the app is missing permissions. Fix: click **Verify connection** and follow the steps that it shows. You add the missing scopes under OAuth & Permissions in the Slack app settings, then reinstall the app.
**Verify connection says Slack rejected the bot token or the app-level token.**
Cause: the token was reset, or the app was reinstalled and got a new token. Fix: connect the app again with the new tokens in the **Connect an app** form. Squad replaces an app whose old token Slack no longer accepts.
**Squad says the app is already connected to this workspace.**
Cause: the app's current tokens still work, so the app is connected. Fix: nothing to do. To change to other tokens, remove the app and connect it again.
**Squad says the tokens belong to two different Slack apps.**
Cause: you copied the tokens from two apps. Fix: copy the app-level token from Basic Information and the bot token from Install App of the same app.
**Squad says that is the bot's own ID.**
Cause: you typed the app's member ID. Fix: type your own member ID from your Slack profile.
**The error says this is the primary Slack app and other apps are still connected.**
Cause: the primary app is removed last. Fix: remove the other apps first, then remove this one.
### Messages when you connect an app
| Message | Cause | Fix |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------------------------- |
| "That doesn’t look like a Slack bot token — it starts with xoxb-." | The bot token field has another token. | Paste the Bot User OAuth Token from Install App. |
| "That doesn’t look like a Slack app-level token — it starts with xapp- (Basic Information → App-Level Tokens)." | The app-level token field has another token. | Paste the app-level token from Basic Information. |
| "That doesn’t look like a Slack member ID (it starts with U — …)." | The member ID is not valid. | Copy your member ID from your Slack profile. |
| "Slack rejected that bot token — reinstall the app to your workspace and paste the fresh xoxb- token." | The bot token is old or was revoked. | Reinstall the app, then paste the new bot token. |
| "That app-level token can’t open connections — generate it with the connections:write scope." | The app-level token has no `connections:write` scope. | Generate a new app-level token with that scope. |
| "Slack rejected that app-level token — make sure Socket Mode is ON and paste the xapp- token from Basic Information → App-Level Tokens." | Socket Mode is off, or the token is wrong. | Turn on Socket Mode in the Slack app settings, then paste the token again. |
| "Couldn’t reach Slack to verify the token — try again." | Squad could not reach Slack. | Wait a moment, then try again. |
| "This workspace has several Slack apps from an earlier setup and none of them is the primary. Remove the apps you don’t need in Settings, then connect this one." | Old apps are left over, and none is the primary app. | Remove the apps that you do not need, then connect again. |
| "Couldn’t check your existing Slack apps to make sure this one isn’t already connected. Try again in a moment." | Squad could not check the apps that are already connected. | Try again in a moment. |
| "Couldn’t connect the app." | The connection did not go through. | Try again. |
### Results of Verify connection
| Result | What to do |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| A green message that starts with "Connected" | Nothing. The app has every permission it needs. |
| "The Slack app is missing a permission Squad needs to reply:" (or "missing permissions") followed by the scopes | Follow the steps in the message: add the scopes under OAuth & Permissions, reinstall the app, then click **Verify connection** again. |
| "Slack rejected the app’s bot token (…)" | Copy a new Bot User OAuth Token and connect the app again. |
| "Slack rejected the app-level token (…), so the live connection can’t open." | Create a token with the `connections:write` scope and connect the app again. |
| "The two tokens belong to two different Slack apps, …" | Copy both tokens from the same app and connect it again. |
| "Slack couldn’t be reached from your squad’s computer just now. That is usually momentary." | Click **Verify connection** again. |
The Verify messages say to paste new tokens "here in Squad". The card has no token field. Use the **Connect an app** form instead, as the troubleshooting entry about rejected tokens above describes.
For list messages and messages that all channel screens share, see [Messages on every channel screen](/docs/channels#messages-on-every-channel-screen). The list messages are "Slack member IDs start with U, e.g. U0123ABCDEF." and "Keep at least one person — an empty list answers nobody."