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

# Slack Bot

> Enable your team to ask questions directly in Slack

The nao Slack bot brings your analytics agent directly into Slack, allowing your team to ask questions and get insights without leaving their workspace.

![nao Slack Bot Interface](https://mintcdn.com/naolabs/dXmKsWCxaX80SatB/images/nao-agent/slack.png?fit=max\&auto=format\&n=dXmKsWCxaX80SatB\&q=85\&s=343788812eb0820dcf15ecbc72a796f7)

When configured, the nao Slack bot:

* Listens for mentions in Slack channels
* Can also answer from direct messages in Slack
* Processes questions using the same agent as the web chat interface
* Returns answers with SQL queries, data tables, and visualizations
* Maintains conversation context within Slack threads
* Streams progress updates and can upload CSV outputs for query results

> [!NOTE]
>
> The Slack bot uses the same agent context, rules, and capabilities as your web
> chat interface. Any improvements to your agent automatically benefit Slack
> users.

## Setup

### Step 1: Create your Slack App

1. In nao, open **Settings** -> **Integrations & MCP** -> **Slack**
2. Verify your deployment URL
3. Click **"Create Slack App"**

This opens Slack with a pre-filled app manifest: scopes, event subscriptions, and interactivity are configured automatically.

### Step 2: Install the App to your Workspace

1. In your Slack app settings, go to **"Install App"**
2. Click **"Install to Workspace"** and allow the permissions

### Step 3: Connect your Slack Bot to nao

1. In **"OAuth & Permissions"**, copy the **Bot User OAuth Token** (starts with `xoxb-`) and paste it as **Bot Token** in nao
2. In **"Basic Information"**, copy the **Signing Secret** and paste it as **Signing Secret** in nao
3. Click **"Save"**

### Step 4: Add Bot to Channels

1. In Slack, go to any channel where you want the bot
2. Type `/invite @nao` (or your bot's name)
3. The bot will now listen for mentions in that channel

### Optional: Socket Mode for private VPC deployments

Use **Socket Mode** when nao runs inside a private VPC or air-gapped environment without a public webhook URL.

1. In your Slack app under **Settings -> Socket Mode**, enable Socket Mode and generate an **App-Level Token** with `connections:write` scope (starts with `xapp-`).
2. In nao Slack settings, switch the **Transport mode** toggle from **Webhook** (default) to **Socket Mode**.
3. Paste the App-Level Token. The Bot Token and Signing Secret from Step 3 are still used.
4. Save. nao opens an outbound WebSocket and forwards every event into the same handler the webhook uses, so all Slack features behave identically.

Webhook mode stays the default for public deployments. Switch to Socket Mode only when you cannot expose an inbound URL.

### Optional: Auto-create users from Slack

When a teammate mentions the bot from a workspace email that matches an **allow list** you configure, nao auto-creates a user account on first use - no manual invite needed.

1. In nao Slack settings, open the **User auto-creation** section.
2. Add the email domains or specific addresses allowed to self-onboard (e.g. `@your-company.com`).
3. Save. The next time someone in the allow list mentions `@nao`, an account is provisioned with the default role (see [Add Users](https://docs.getnao.io/nao-agent/chat/admin/setup.md#add-users)).

Leave the allow list empty to keep manual user provisioning only.

### Optional: Reply mode

By default, once you `@nao` in a thread the bot stays engaged and replies to every following message in that active thread. Admins can change this so the bot only answers messages that explicitly mention it.

1. In nao Slack settings, open the **Settings** card.
2. Toggle **Reply only when mentioned**:
   * **Off** (default) - after the first mention, the bot keeps answering follow-ups in that thread without needing another `@nao`. The Connection card shows `Replies: Every message in active threads`.
   * **On** - nao still reads thread context but only answers messages that tag the bot. The Connection card shows `Replies: Only when mentioned`.

The setting saves immediately and applies to the whole project. Only admins can change it; other members see the current mode on the Connection card.

Use **Reply only when mentioned** in busy shared channels where you want tighter control over when the bot speaks.

### Optional: Configure Slack from environment variables

On a self-hosted deployment you can seed the Slack connection declaratively instead of pasting tokens in the UI. Set these environment variables and nao writes the default project's Slack settings on boot:

| Variable | Purpose |
| - | - |
| `SLACK_BOT_TOKEN` | Bot User OAuth Token (`xoxb-`). Setting it is what enables the seed. |
| `SLACK_SIGNING_SECRET` | Signing Secret. Required for webhook transport. |
| `SLACK_APP_TOKEN` | App-Level Token (`xapp-`). Required for Socket Mode. |
| `SLACK_TRANSPORT_MODE` | `socket` or `webhook`. Overrides the inferred transport. |

When `SLACK_BOT_TOKEN` is set, transport defaults to `socket` if `SLACK_APP_TOKEN` is present and `webhook` otherwise; `SLACK_TRANSPORT_MODE` overrides that choice. Invalid combinations fail startup validation with an actionable message: Socket Mode without an app token, webhook without a signing secret, or any `SLACK_*` variable set without the bot token.

The seed only owns the credential and transport fields. UI-managed settings - model selection, reply mode, auto-created users - are preserved. It is idempotent (no write when the stored config already matches) and never blocks startup: with no project yet, it skips with a warning. While the variables stay set, their values re-assert on every boot, which is the declarative intent; the **Settings** -> **Slack** form keeps working for everything else.

## Usage

**Ask Questions**

Mention the bot in any channel where it's been added:

```
@nao What were our top 5 products by revenue last month?
```

The bot will:

1. Process your question using the same agent as the web interface
2. Generate SQL queries based on your context
3. Execute queries against your connected databases
4. Return results in a formatted Slack message
5. Send you the link to the full conversation to open it in browser UI

**Thread Conversations**

Follow-up questions in the thread maintain context:

```
@nao What were our top 5 products by revenue last month?
# ... bot responds ...

@nao Can you break that down by region?
# ... bot responds with regional breakdown ...
```

> [!NOTE]
>
> The bot replies in threads to keep conversations organized. Use thread replies
> for follow-ups.

**Direct Messages**

You can also ask the bot in Slack direct messages (no channel mention required).

**Starting a fresh chat with `/new`**

In a direct message or a private channel, a conversation with nao keeps its context indefinitely. Use `/new` to draw a line under it:

* **`/new`** on its own ends the current chat. Whatever you send next starts a fresh one.
* **`/new <question>`** starts a fresh chat *and* opens a thread for it, headed by your question, with the agent answering inside that thread. The main conversation stays free, so you can run several independent chats side by side - one per thread.

`/new <question>` is only available in direct messages and private channels. In a public channel, send `/new` on its own.

**Reading the thread when mentioned mid-conversation**

When you `@nao` inside an existing Slack thread, the bot reads the previous messages in that thread before answering. This means you can have a human discussion first and then loop nao in with a question like `@nao can you pull the numbers for this?` - it will pick up the earlier context without you having to restate the question.

**Tables and formatting**

Markdown tables in the agent's answer are rendered as native Slack tables instead of raw pipe characters, so query results stay readable in the channel. Text around a table is split into separate blocks and converted to Slack formatting: headings and bold become bold text, and code spans and fenced code blocks are left untouched. This applies to streamed replies as well as messages posted by automations.

**Compact view**

A **compact view** mode renders nao's replies as shorter Slack messages: SQL and large tables are collapsed behind links so the channel stays readable, and full results are available in the linked web conversation. Toggle it under **Settings** -> **Integrations & MCP** -> **Slack**. Use compact view in busy channels and the default (expanded) view when you want the full SQL and data inline.

**Stop Conversations**

While generating, you will see a "stop generation" button appear in the slack conversation.
Click on that button if you want to stop the chat from generating more text.

**What's Next?**

> [card] [Chat Overview](https://docs.getnao.io/nao-agent/chat/overview.md)
>
> Learn about the web chat interface

> [card] [Self-Hosting Guide](https://docs.getnao.io/nao-agent/self-hosting/deployment-guide.md)
>
> Deploy nao with Docker or on your own Cloud Run instance


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.