> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpander.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Slack workspace
> Connect a Slack workspace once, set workspace-wide behavior, authorize agent handles, and disconnect. For organization admins.
One xpander Slack app serves the whole workspace. An organization admin connects it once. What members do with it is on [Agents in Slack](https://docs.xpander.ai/guides/deploy/slack.md).
## Connect the workspace
**1. Start from an agent**
Open any agent's **Channels** pane. Under **Slack channels**, click Connect Slack (admins only). **Platform > Agents > Channels** opens in a new tab.
**2. Connect Slack**
Click Connect Slack, review the permissions in the Slack window, and click Allow.
**3. Done**
The workspace shows as connected. Members can DM the app right away.
Members who are not admins see **Ask an admin to connect Slack**. Where your operator manages the Slack app, everyone sees **Ask your operator to set up the Slack app**. A workspace can be connected to one xpander organization at a time.
Platform > Agents > Channels on an Air-Gapped install: Slack, Microsoft Teams and Email are on, and MCP is not offered. Shown with sample data.
### Disconnect the workspace
Disconnect in xpander, or remove the app in Slack (**Settings & administration → Manage apps → xpander → Remove App**). Either way, the app leaves everyone's sidebar, past DMs follow Slack's retention, and xpander keeps the channel routing. Reconnecting the same workspace restores it.
## Workspace-wide settings
On **Platform > Agents > Channels**, click a channel to open it. **On for everyone** turns it on or off. Off pauses the channel and keeps conversations. xpander cloud lists WhatsApp, Slack, Microsoft Teams and Telegram. A self-hosted install lists Slack, Microsoft Teams, Email (once a mailer is set) and MCP ([when MCP is offered](https://docs.xpander.ai/run/integrations/mcp-gateway.md#on-an-air-gapped-install)).
The Slack entry holds the workspace-wide **Slack behavior** options and every channel routed to an agent. **Show detailed tool activity** turns the step list on for every channel, and a channel row can override it. User groups decide who configures which channel sections under **Triggers**. Changes are logged in **Platform > AI governance > Audit log** as `Org Channels Updated`.
## Authorize handle management
A handle such as `@account-research` lets people pick an agent from Slack's mention picker. It needs a one-time authorization by an **xpander organization admin** whose Slack account can create, edit and deactivate user groups. It is separate from connecting the app, and needs a paid Slack plan.
**1. Keep Slack group permissions restricted**
Use a Slack admin account with user-group rights (**Permissions → User Groups**). Everyone else can stay restricted. See [Slack's group-management requirements](https://docs.slack.dev/reference/methods/usergroups.create/#usage-info).
**2. Authorize from workspace settings**
In **Platform > Agents > Channels**, **Slack**, select Authorize agent handles, confirm the connected workspace, and approve the user-group permission.
**3. Return to xpander**
The workspace shows **Authorized**. Agent owners can now create, rename and delete their agents' handles, and organization admins can manage any agent's handles.
**Authorized** means setup is complete: xpander verified the bot's permissions, saved the admin grant in Vault and enabled handles. Nothing else needs activating. Slack checks the account's rights on each handle change. Authorizing does not create any handle.
The user token and refresh token are encrypted in **Supabase Vault**. The browser and the agent's skills never receive them. Messages still go through the existing bot connection.
## Reauthorize when needed
If the authorizing account loses its rights or its grant is revoked, select **Reauthorize**. Until then, existing handles keep working, creating or renaming waits, and deleting removes the mapping at once (Slack cleanup waits).
| Button | When | What it refreshes |
| - | - | - |
| **Reconnect** (bot) | Authorization asks for updated app permissions. Then select **Authorize agent handles** again | The bot permission grant |
| **Reauthorize** (user) | The authorizing account lost its rights or its grant | The admin user-group grant |
Reconnecting or disconnecting clears handle authorization, so authorize again afterwards. Workspaces authorized before automatic setup existed need one more authorization too.
## Next steps
> **[Use agents in Slack](https://docs.xpander.ai/guides/deploy/slack.md)**
>
> DMs, handles and channels.
> **[Connect a Microsoft Teams tenant](https://docs.xpander.ai/run/integrations/microsoft-teams.md)**
>
> The same for Microsoft 365.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.