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

# Slack

> Connect your agent to Slack workspaces

## Overview

Slack integration allows your agent to participate in workspace conversations - perfect for internal teams or community support.

<CardGroup cols={2}>
  <Card title="Team Collaboration" icon="users">
    Internal communication
  </Card>

  <Card title="Real-Time" icon="bolt">
    Instant messaging
  </Card>

  <Card title="Developer Friendly" icon="code">
    Popular with tech teams
  </Card>

  <Card title="Two Types" icon="list">
    Private Bot or Public App
  </Card>
</CardGroup>

## Two integration types

Slack supports two connection styles. The admin dashboard wizard walks you through either one and **generates the Slack app manifest for you**, so you don't have to configure scopes and event subscriptions by hand.

<Tabs>
  <Tab title="Private (bot token)">
    **Just your workspace**

    * Single workspace
    * Authenticates with a bot token (`xoxb-...`)
    * Simplest option for internal team use

    Available in the dashboard and CLI.
  </Tab>

  <Tab title="Public (distributable app)">
    **A distributable app**

    * Installable by other workspaces
    * Authenticates with App ID, Client ID and Client Secret
    * For distributing your agent beyond your own workspace

    Available in the dashboard.
  </Tab>
</Tabs>

## Connection Method 1: Admin Dashboard (Recommended)

<Info>
  The dashboard provides a guided wizard and **generates a ready-to-paste Slack app manifest** after you connect, so you don't configure scopes, event subscriptions, or interactivity by hand.
</Info>

<Steps>
  <Step title="Open the dashboard">
    ```bash theme={null}
    lua admin
    ```

    Or visit [https://admin.heylua.ai](https://admin.heylua.ai).
  </Step>

  <Step title="Open your agent and add a channel">
    Click **Agents** in the main side navigation, select your agent's card, click the **+** (plus) icon to add a channel, then choose **Slack**.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-add-channel.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=ab13d8f9a731bc706b9e112cf4226701" alt="Add a channel" width="3016" height="1576" data-path="images/channels/admin-add-channel.png" />
    </Frame>

    *Screenshot: The agent's add-channel (+) control and the channel options*
  </Step>

  <Step title="Choose how to connect">
    Pick the connection type:

    * **Private — just my workspace**: use a bot token from a Slack app you control. Simplest if you only need the agent inside your own workspace.
    * **Public — a distributable app**: build a Slack app other organizations can install.

    Not sure? Start with **Private** — you can always add a public app later.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-slack-connect-type.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=6c0b6f72d77671f2ca4b43402207539f" alt="Choose Slack connection type" width="3022" height="1570" data-path="images/channels/admin-slack-connect-type.png" />
    </Frame>

    *Screenshot: The "Connect to Slack" step with the Private and Public choices*
  </Step>

  <Step title="Create your Slack app">
    If you don't already have one, the wizard walks you through creating it at [api.slack.com/apps](https://api.slack.com/apps) → **Create New App** → **From scratch**. Give it any name and pick your workspace.

    <Tabs>
      <Tab title="Private (bot token)">
        1. In your app, open **OAuth & Permissions** and add the [bot token scopes](#required-bot-scopes) your agent needs.
        2. Click **Install to Workspace** and approve the permissions.
        3. Copy the **Bot User OAuth Token** — it starts with `xoxb-`.

        Treat the bot token like a password — anyone with it can act as your bot.
      </Tab>

      <Tab title="Public (app credentials)">
        1. Open **Basic Information → App Credentials**.
        2. Copy your **App ID**, **Client ID**, and **Client Secret** (click **Show** to reveal the secret).

        You don't need to set up scopes, redirect URLs, or event subscriptions yet — Lua generates a manifest for that after you connect.
      </Tab>
    </Tabs>
  </Step>

  <Step title="Enter your credentials">
    Paste your details into the wizard and click **Connect**.

    * **Private**: your bot token (`xoxb-...`).
    * **Public**: App ID, Client ID, and Client Secret.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-slack-credentials.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=057617032e6eefb193e0e10737adad1b" alt="Enter Slack credentials" width="3016" height="1574" data-path="images/channels/admin-slack-credentials.png" />
    </Frame>

    *Screenshot: The credentials step (bot token, or App ID / Client ID / Client Secret)*
  </Step>

  <Step title="Finish in Slack (apply the manifest)">
    After connecting, Lua shows a generated **app manifest**. Copy it, then in Slack open **App Manifest**, switch to the **JSON** tab, paste it in, and click **Save Changes**. This sets up the permissions and event subscriptions your agent needs.

    <Frame>
      <img src="https://mintcdn.com/luaglobal/5airD3u2P6mv3Ovl/images/channels/admin-slack-finish.png?fit=max&auto=format&n=5airD3u2P6mv3Ovl&q=85&s=894b5b80ea90dde1b12170cc1977851b" alt="Apply Slack manifest" width="3018" height="1578" data-path="images/channels/admin-slack-finish.png" />
    </Frame>

    *Screenshot: The "finish in Slack" dialog with the generated manifest*

    <Warning>
      **Public apps:** use the **Add to Slack** button in the dialog to install. Don't use Slack's green **Install to Workspace** button on the Install App page — it creates a token inside Slack but never finishes the connection to Lua.
    </Warning>
  </Step>

  <Step title="Start chatting">
    DM your bot in Slack, or **@mention** it in a channel it's been invited to, and your agent will reply.
  </Step>
</Steps>

## Required bot scopes

Add these **Bot Token Scopes** under **OAuth & Permissions**. The dashboard manifest includes them automatically; you only add them by hand for the private bot or CLI paths.

* `chat:write` — Send messages
* `channels:history` — Read public channel messages
* `groups:history` — Read private channel messages
* `im:history` — Read direct messages
* `mpim:history` — Read group direct messages
* `channels:read` — List public channels
* `groups:read` — List private channels
* `im:read` — List direct messages
* `mpim:read` — List group direct messages
* `users:read` — View user information
* `users:read.email` — View user emails
* `app_mentions:read` — Detect @mentions
* `files:read` — Access uploaded files

<AccordionGroup>
  <Accordion title="Message Scopes">
    **Reading messages:**

    * `channels:history` - Read public channel messages
    * `groups:history` - Read private channel messages
    * `im:history` - Read direct messages
    * `mpim:history` - Read group direct messages

    **Sending messages:**

    * `chat:write` - Required to send any messages
  </Accordion>

  <Accordion title="Channel Scopes">
    **Reading channel info:**

    * `channels:read` - List public channels
    * `groups:read` - List private channels
    * `im:read` - List DMs
    * `mpim:read` - List group DMs
  </Accordion>

  <Accordion title="User Scopes">
    **User information:**

    * `users:read` - Get user display names
    * `users:read.email` - Get user email addresses

    **Useful for:**

    * Personalizing responses
    * User identification
    * Profile information
  </Accordion>

  <Accordion title="Additional Scopes">
    **Other features:**

    * `app_mentions:read` - Detect when bot is @mentioned
    * `files:read` - Read uploaded files
  </Accordion>
</AccordionGroup>

## Connection Method 2: CLI (Private Bot)

The CLI connects a **private** bot using a bot token. Create your Slack app at [api.slack.com/apps](https://api.slack.com/apps), add the [required scopes](#required-bot-scopes), install it to your workspace, and copy the bot token first.

```bash theme={null}
$ lua channels
✅ Using agent: myAgent

? What would you like to do? 🔗 Link new channel
? Select channel type: 🔒 Slack (Private)

? Enter Slack bot token (xoxb-...): ****

📡 Creating Slack channel...

✅ Slack channel created successfully!

💼 Bot Name: My Agent Bot
🏢 Workspace: My Company
🔗 Webhook: https://wa.heylua.ai/slack/webhook
```

<Note>
  For the CLI path you configure the Slack app yourself. Set both **Event Subscriptions** and **Interactivity** request URLs to `https://wa.heylua.ai/slack/webhook`, and subscribe to the `app_mention`, `message.channels`, `message.groups`, and `message.im` bot events. The dashboard does this for you via the generated manifest.
</Note>

## Testing

DM your bot in Slack (or **@mention** it in a channel it's been invited to). Your agent replies automatically. Monitor the conversation in the admin dashboard.

## Next Steps

<CardGroup cols={2}>
  <Card title="Email" icon="envelope" href="/channels/email">
    Add email support
  </Card>

  <Card title="Management" icon="wrench" href="/channels/cli-management">
    Manage all channels
  </Card>
</CardGroup>