> ## 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

> One xpander app for your whole Slack workspace: DM your Omni, mention it anywhere, and route channels to your agents

xpander connects to Slack through a single workspace app. Once your workspace is connected, everyone gets their own AI assistant in Slack, and any channel can be routed to one of your organization's agents.

## How it responds

The app decides who answers based on how a message arrives:

| You...                                           | Who answers                                                                                                     |
| ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------- |
| **DM the app**                                   | Your personal Omni - the same assistant and conversation history you have in the xpander app                    |
| **@mention the app** in any channel or thread    | Your personal Omni, replying in a thread as **"your-name's Omni"** so everyone sees whose assistant is speaking |
| **Post an untagged message** in a routed channel | The agent routed to that channel, when the message matches its engagement rules                                 |

Replies from a routed agent are posted under **that agent's name and icon**, and channel replies from a personal Omni are posted as **"‹name›'s Omni"** - a channel always shows exactly who answered. DMs keep the app's own identity. After you @mention the app in a thread, your follow-up replies in that thread keep reaching your Omni for a few minutes - no need to re-mention it on every message.

Everyone always talks to **their own** Omni, with their own context and permissions - even in a shared channel or the same thread. If two people are chatting with the app in one thread, each reply is labelled with that person's name (**"Dana's Omni"**, **"Sam's Omni"**), and neither person's Omni sees or acts on the other's private data. There is no shared or company-wide Omni.

## Connect the workspace

A Slack workspace connects to your xpander organization once, workspace-wide, by an **organization admin**. After that, no per-user or per-agent setup is needed.

<Steps>
  <Step title="Open Channels settings">
    In the xpander app, open **Settings** and pick the **Channels** tab (admins only).
  </Step>

  <Step title="Connect Slack">
    Click <kbd>Connect Slack</kbd>. A Slack window opens asking you to authorize the xpander app for your workspace - review the permissions and click <kbd>Allow</kbd>.
  </Step>

  <Step title="Done">
    The window closes on its own and the Channels tab shows your workspace as connected. Members can start DMing the app immediately.
  </Step>
</Steps>

A Slack workspace can be connected to one xpander organization at a time. Admins can disconnect from the same place - this uninstalls the xpander app from the Slack workspace, so it disappears from everyone's sidebar (past DM history remains visible, per Slack's retention). Your channel routing is kept on the xpander side, and reconnecting the same workspace restores it. If you are not an admin and Slack shows as not connected, ask an organization admin to connect it.

## Talk to your Omni

<Steps>
  <Step title="DM the app">
    Find the xpander app in your Slack sidebar and send it a message.
  </Step>

  <Step title="Automatic sign-in">
    If your Slack email matches your xpander account, you're linked automatically and the answer arrives right away. Otherwise you'll get a **Link account** button - one click connects your Slack to your xpander profile.
  </Step>

  <Step title="Work as usual">
    Your Slack DM is a real Omni conversation: it appears in the xpander app's sidebar, remembers context, runs tools, and builds dashboards. Replies stream in as the agent works. Send `new chat` (or `reset`) to start a fresh conversation.
  </Step>
</Steps>

Voice notes are transcribed, images are read, and attached files are processed automatically. When an agent builds a dashboard or visual, the reply carries a **View here** button that opens it full-screen in the browser - no sign-in needed.

You can also **build and update agents right from the DM**: Omni asks its setup questions with tappable buttons, sends you authorization links for the accounts your agent needs, and creates the agent the moment you tap **Approve & build** - it appears in the xpander app right away. Connectors that require MCP setup are the one exception: Omni hands you a link to finish those in the app.

## Route a channel to an agent

Untagged channel messages can be handled by one of your organization's agents. Any member can set this up.

<Steps>
  <Step title="Open Slack channel settings">
    In the xpander app, open your agent's settings and find **Slack channels**, or use the channel selector under the Omni composer. Both open the same surface.
  </Step>

  <Step title="Pick a channel and an agent">
    Choose the Slack channel and the agent that should own its untagged traffic, then click <kbd>Add</kbd>. The app joins public channels automatically; for private channels, invite it with `/invite` so it can see messages.
  </Step>

  <Step title="Write engagement rules">
    Expand **Rules** on the channel row. Each rule is a plain-language description of when the agent should step in - the agent engages when a message matches **any** rule. Rules apply within a minute; no publish step is needed.
  </Step>
</Steps>

Write rules as specific intent descriptions, not keyword lists:

* ✅ "When someone reports a bug, error, or outage"
* ✅ "When a question about pricing or plans goes unanswered"
* ❌ "bug, error, pricing" (too broad - triggers on most messages)

A routed agent answers **in a thread**, acting on behalf of the message author. Direct @mentions in a routed channel still go to the author's own Omni - routing only applies to untagged messages. Once the agent engages in a channel, it follows the conversation for a few minutes without re-checking the rules on every message.

Routing looks at **top-level channel messages**. Untagged thread replies don't engage the agent unless you turn on **Also engage in thread replies** on the channel row - an @mention inside a thread always works.

## Where conversations live

* **DM conversations** appear in your xpander sidebar like any other Omni conversation.
* **Channel conversations** (mentions and routed replies) stay out of the personal sidebar but are visible under the organization's **Tasks**, where every run is tracked.

## Troubleshooting

<AccordionGroup>
  <Accordion title="The routed agent doesn't respond in a channel">
    The app must be a member of the channel - check the member list and `/invite` it if needed (always required for private channels). Then check that the channel row's auto-engage toggle is on and that a rule actually matches your message. If the message was a reply inside a thread, note that thread replies only engage when **Also engage in thread replies** is enabled on the channel row (or when the app is @mentioned). Rule edits take up to a minute to apply.
  </Accordion>

  <Accordion title="The app says the organization is out of credits">
    Runs stop with a billing notice when your organization's credits run out. An organization admin can top up under **Settings** in the xpander app - then send your message again.
  </Accordion>

  <Accordion title="The agent responds when it shouldn't">
    Tighten the rules: overly broad conditions like "when someone asks a question" match most messages. Note that after an engagement, follow-ups in the same channel may engage without re-checking rules for a few minutes.
  </Accordion>

  <Accordion title="I get a link-account prompt instead of an answer">
    Your Slack email doesn't match an xpander account in this organization. Tap **Link account** to connect, or ask your admin to invite that email to the organization.
  </Accordion>
</AccordionGroup>

<Info>
  The previous per-workspace **Slack Agents** flow (creating a Slack agent with configuration tokens under `app.xpander.ai/slack_agents`) is deprecated. Existing Slack agents created that way keep working until you migrate them to channel routing.
</Info>

## Next Steps

<CardGroup cols={2}>
  <Card title="Chat Widget" icon="browser" href="/guides/deploy/chat-widget">
    Share a chat URL or embed in your website
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/deploy/webhooks">
    Trigger agents from external systems
  </Card>
</CardGroup>