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

# Slack (Nebuly AI agent)

> Install Nebuly AI agent in Slack, configure the integration, and ask analytics questions with your own Nebuly account

**Last verified: October 2026**

Nebuly AI agent answers analytics questions in Slack. Each person only sees data their own Nebuly account can access—the same permissions as in the Nebuly web app.

> [!NOTE]
>
> The Slack integration is in **beta**. Your environment must have the [Nebuly
> MCP server](https://docs.nebuly.com/documentation/nebuly-ai/mcp-server.md) enabled.

## Installation overview

Setting up Nebuly AI agent in Slack involves these phases:

1. **Create the Slack app** (self-hosted only): create from manifest, app-level token, then credentials in Nebuly settings or environment variables.
2. **Configure the AI model and enable Slack**: provider, model, and API key in **Settings > Integrations**.
3. **Add Nebuly to your Slack workspace**: install the app when the integration shows **Ready**.
4. **Add Nebuly AI agent to channels**: invite Nebuly AI agent where you want to ask questions.
5. **Connect Nebuly** (each user): one-time OAuth so questions use that user's MCP access.

## Prerequisites

**Nebuly admin**

* Permission to manage tenant settings (for example `admin:*`).
* An API key for **OpenAI**, **Anthropic**, or **Google** to power answers in Slack.
* Access to **Settings > Integrations** in the Nebuly web app.

**Slack workspace admin**

* Permission to install apps in the target Slack workspace.

**Self-hosted operator** (in addition to the above)

* The optional `slackBot` Helm component deployed and reachable at a public `BOT_URL`.
* `NEXT_PUBLIC_SLACK_BOT_URL` on the Nebuly frontend pointing at the same bot URL.
* Network path from the bot to the tenant registry (`/api/internal`) and the backend (`/internal`). Restrict registry `/api/internal/slack` routes to the bot only.
* The bot must reach the public `MCP_SERVER_URL` and its authorization server (for **Connect Nebuly**).
* Every bot replica must use the same `SLACK_BOT_ENCRYPTION_KEY`.
* Slack OAuth redirect: `{BOT_URL}/slack/oauth_redirect` (already in the manifest).
* **Connect Nebuly** callback: `{BOT_URL}/oauth/callback` (used with your MCP server sign-in; do not add it to the Slack app).

## Step 1: Create the Slack app (self-hosted only)

> [!NOTE]
>
> On **Nebuly Cloud**, Nebuly operates the Slack app. Skip this step and go to
> [Step 2](#step-2-configure-the-ai-model-and-enable-slack).

You can provide Slack app credentials in **Settings > Integrations** or as environment variables on the Slack bot deployment. Either way, you must create the Slack app in the [Slack API](https://api.slack.com/apps) dashboard first. If you use environment variables, create the app by pasting the manifest below—the Nebuly **Create app from manifest** button may not be available until the bot URL is configured.

1. **Create the app.**

> [!NOTE]
>
> Use **Paste the manifest** if you configure credentials with environment variables or do not see **Create app from manifest** in the Nebuly UI.

> [tab] From Nebuly settings
>
> 1. Open **Settings > Integrations** in the Nebuly web app.
> 2. On the **Slack** card, click **Manage**.
> 3. In the **Slack app** section, click **Create app from manifest** and complete the flow in the [Slack API](https://api.slack.com/apps) dashboard.
>
>    ![Integrations cards](https://mintcdn.com/nebulyai/YN48FJ3IP2fr_Hh2/images/slack/integrations-cards.png?fit=max\&auto=format\&n=YN48FJ3IP2fr_Hh2\&q=85\&s=8fd70b1b296d4645064e36b5a89c1edf)
>
>    ![Slack app section](https://mintcdn.com/nebulyai/YN48FJ3IP2fr_Hh2/images/slack/slack-app-section.png?fit=max\&auto=format\&n=YN48FJ3IP2fr_Hh2\&q=85\&s=8850dbd74d20d4a533e14d4596150437)

> [tab] Paste the manifest
>
> 1. Open the [Slack API](https://api.slack.com/apps) dashboard and click **Create New App**.
>
> 2. Choose **From a manifest**, select a development workspace, and click **Next**.
>
> 3. Open the **YAML** tab, paste the manifest below, and click **Next**, then **Create**.
>
> > [!WARNING]
> >
> > Replace `<BOT_URL>` with your bot's public URL (include any ingress path prefix, no trailing slash) before pasting.
>
> ```yaml theme={null}
> display_information:
>   name: Nebuly AI agent
>   description: Nebuly AI agent answers your Nebuly analytics questions from Slack
>   background_color: "#0a4fff"
> features:
>   bot_user:
>     display_name: Nebuly AI agent
>     always_online: true
>   slash_commands:
>     - command: /nebuly-project
>       description: Set the Nebuly project for this channel or DM
>       usage_hint: "[project name]"
>       should_escape: false
>   app_home:
>     home_tab_enabled: false
>     messages_tab_enabled: true
>     messages_tab_read_only_enabled: false
> oauth_config:
>   redirect_urls:
>     - <BOT_URL>/slack/oauth_redirect
>   scopes:
>     bot:
>       - app_mentions:read
>       - channels:history
>       - chat:write
>       - commands
>       - groups:history
>       - im:history
>       - mpim:history
>       - users:read
> settings:
>   event_subscriptions:
>     bot_events:
>       - app_mention
>       - message.im
>       - app_uninstalled
>       - tokens_revoked
>   interactivity:
>     is_enabled: true
>   org_deploy_enabled: false
>   socket_mode_enabled: true
>   token_rotation_enabled: false
> ```

2. **Upload the app icon** (see [Upload the app icon](#upload-the-app-icon)). Slack manifests cannot set an icon.
3. Under **Basic Information > App-Level Tokens**, create a token with scope **`connections:write`**. Copy the `xapp-…` value.
4. Copy **Client ID** and **Client Secret** from **Basic Information** (not a bot token; install creates tokens per workspace).
5. **Provide the credentials to Nebuly.**

> [tab] Nebuly settings
>
> Open **Settings > Integrations**, **Manage** on the **Slack** card, and paste **Client ID**, **Client secret**, and **App token** in the **Slack app** section.

> [tab] Environment variables
>
> Set `SLACK_CLIENT_ID`, `SLACK_CLIENT_SECRET`, and `SLACK_APP_TOKEN` on the Slack bot deployment, then restart or redeploy the bot.
>
> All three must be set. If any is missing, the bot falls back to credentials saved in **Settings > Integrations**.
>
> When all three are set, they override the UI. The integrations drawer shows those fields as read-only (**Configured by your deployment**).
>
> You still complete [Step 2](#step-2-configure-the-ai-model-and-enable-slack) (AI model) in the UI. **Connect Nebuly** uses your Nebuly MCP server's sign-in—no extra OAuth client setup is needed.

### Upload the app icon

Slack app manifests cannot set an icon, so add it by hand after creating the app:

1. Download the Nebuly app icon: [nebuly-slack-app-icon.png](https://docs.nebuly.com/images/slack/slack-app-icon.png) (PNG, 512×512).
2. In the [Slack API](https://api.slack.com/apps) dashboard, open your app and go to **Basic Information > Display Information**.
3. Next to **App icon**, click **Add App Icon** and select the downloaded file.
4. Click **Save Changes**.

![Nebuly Slack app icon](https://mintcdn.com/nebulyai/YN48FJ3IP2fr_Hh2/images/slack/slack-app-icon.png?fit=max\&auto=format\&n=YN48FJ3IP2fr_Hh2\&q=85\&s=a593a2bcaba0e40277a252fb552aa686)

## Step 2: Configure the AI model and enable Slack

1. In the same **Manage** drawer, open the **AI model** section.
2. Choose **Provider**, then **Model** (select from the list or type a custom model ID), then **Key**.
3. Click **Save and enable**.

Nebuly validates required fields when you save. On self-hosted, the **Slack app** section is included in that check. The API key is verified before settings are stored. If you change **Provider**, you must enter a new **Key**.

When save fails, errors tied to a field appear under that field (for example **Invalid API key** under **Key**, **Model not found for this provider** under **Model**, Slack app credential errors under **Client ID**, **Client secret**, or **App token**). Other AI model check failures appear next to **Add to Slack** as **AI model check failed: …** (see Step 3).

![AI model section](https://mintcdn.com/nebulyai/YN48FJ3IP2fr_Hh2/images/slack/ai-model-section.png?fit=max\&auto=format\&n=YN48FJ3IP2fr_Hh2\&q=85\&s=1afa1681f2e3c6a689824c808a659d4f)

## Step 3: Add Nebuly AI agent to your Slack workspace

1. In the **Workspace** section, wait until the status next to **Add to Slack** shows **Ready**, then click the button.
2. A Slack **workspace admin** approves the install.

![Workspace section ready](https://mintcdn.com/nebulyai/YN48FJ3IP2fr_Hh2/images/slack/workspace-ready.png?fit=max\&auto=format\&n=YN48FJ3IP2fr_Hh2\&q=85\&s=f23419d25d2432e9f36bfcae685be88c)

| Status message | What to do |
| - | - |
| Enable integration to connect Slack | Click **Save and enable** in the drawer so Slack is enabled for your tenant. |
| Complete required fields above | Fill in the **Slack app** (self-hosted), **AI model**, and any missing required fields, then save. |
| Checking configuration… | Wait while Nebuly checks Nebuly AI agent and model configuration. |
| Updating configuration… | Wait after a save while Nebuly AI agent reloads settings. |
| Ready | Click **Add to Slack**. |
| AI model check failed: … | Fix the provider, model, or API key; save again. |
| Slack doesn't recognize this Client ID (self-hosted) | Confirm **Client ID** matches the Slack app you created. |
| Slack rejected this app: … (self-hosted) | Check credentials and that `BOT_URL` redirect URLs match your deployment. |

## Step 4: Add Nebuly AI agent to Slack channels

1. Open the Slack channel where you want to use Nebuly.
2. Run `/invite @Nebuly AI agent`, or type `/` and choose **Add apps to this channel**, then select **Nebuly AI agent**.
3. Alternatively, open a direct message with Nebuly AI agent.

> [!TIP]
>
> Start with a small number of channels to test the integration before rolling
> out more widely.

## Step 5: Connect your Nebuly account (each user)

1. @mention Nebuly AI agent or send a direct message with a question.
2. Click **Connect Nebuly** in Nebuly AI agent's reply.
3. Confirm the Slack workspace and Slack user shown on the confirmation page.
4. Sign in with your Nebuly account.

Each teammate repeats these steps once. Answers use only the data that Nebuly account can access.

## Verify the installation

After setup, confirm the following:

1. **Direct message**: Send Nebuly AI agent a question in a DM and receive an answer.
2. **Channel @mention**: @mention Nebuly AI agent in a channel. The answer should be **visible only to you** until you share it.
3. **Share to channel**: Use **Share to channel** to post the answer to the thread for others.
4. **Open in Nebuly**: Use **Open in Nebuly** on an answer (draft links expire after 24 hours).
5. **Default project**: Run `/nebuly-project` to view or set the channel or DM default project.

## Using Nebuly AI agent

* **Ask**: @mention Nebuly AI agent in a channel or send a DM. Channel answers stay private until you share them.
* **AI disclosure**: The first message in each new Slack thread, and the welcome message after you connect, includes a line that you are chatting with Nebuly AI agent, an AI assistant.
* **Share**: Post the same answer to the thread with **Share to channel**.
* **Open in Nebuly** / **Open report**: Open drafts or reports created from Slack in the web app.
* **Reports and charts**: Ask Nebuly AI agent to create or update reports and charts explicitly; it uses your Nebuly permissions.
* **CSV exports**: Not available in Slack. Use **Open in Nebuly** or export from the Nebuly app.
* **Follow up**: Reply in the same thread; Nebuly AI agent uses earlier messages in that thread as context.
* **Feedback**: Use 👍 or 👎 on answers.

## Default project

On first use, you may be asked to pick an organization and project (skipped if you only have one).

Use the **`/nebuly-project`** slash command:

* **`/nebuly-project`** — shows the default project for this channel or DM.
* **`/nebuly-project <project name>`** — sets the default for this channel or DM. The name must match a Nebuly project **exactly** (case-insensitive). Use the project name from the Nebuly UI, not internal report or export identifiers.

In channels, when someone changes the default, Nebuly AI agent posts a short public note. Answers still use the channel or DM default until you change it again.

## Manage the integration

Open **Settings > Integrations**, then **Manage** on the **Slack** card.

| Card badge | Meaning |
| - | - |
| **Not set up** | Slack is not enabled or required configuration is missing. |
| **Disabled** | An admin disabled the integration; Nebuly AI agent does not answer. |
| **Enabled** | Slack is enabled and configuration is healthy. |
| **Needs attention** | Enabled but Nebuly AI agent or the AI model check reported an error. Open the drawer and fix settings. |

* **Disable**: Stops Nebuly AI agent from answering. Users see that Nebuly AI agent in Slack was **disabled by your Nebuly admin**, with a link to **Settings > Integrations**. This is different from never having set up the integration.
* **Save and enable**: Turns the integration back on after configuration is valid.
* **Discard changes**: Closing the drawer with unsaved edits prompts you to discard or keep editing.

## Slack permissions

The Nebuly Slack app requests these **Bot Token Scopes**:

| Scope | Purpose |
| - | - |
| `app_mentions:read` | Receive @mentions in channels |
| `channels:history` | Read public channel messages for thread context |
| `groups:history` | Read private channel messages for thread context |
| `im:history` | Read direct messages |
| `mpim:history` | Read group direct messages |
| `chat:write` | Post answers and ephemeral messages |
| `commands` | Handle `/nebuly-project` |
| `users:read` | Resolve Slack users for Connect Nebuly |

The app also uses **Socket Mode** with an app-level token (`connections:write`). **`im:read`** and **`im:write`** are not required; if your app still lists them from an older manifest, you can remove them when updating the app.

## Privacy

* Each Slack user connects their own Nebuly account.
* Questions are sent to the AI model your Nebuly admin configured, using your organization's API key.
* Nebuly does not store question text in analytics databases. For channel @mentions, private answers are stored for up to 24 hours so you can use **Share to channel**; they are then deleted automatically.
* Removing the app from a workspace deletes the workspace installation and its bot token. After you reinstall the app, each user must complete **Connect Nebuly** again.

## Troubleshooting

### Nebuly AI agent says no AI model is set up

* A Nebuly admin should open **Settings > Integrations**, configure **Provider**, **Model**, and **Key**, and click **Save and enable**.
* Confirm the integration card is not **Disabled**.

### Nebuly AI agent says it was disabled by an admin

* A Nebuly admin should open **Settings > Integrations**, review settings, and click **Save and enable**.
* This message is intentional when an admin clicked **Disable**; it is not the same as missing configuration.

### Add to Slack stays disabled

* Click **Save and enable** and wait until the status shows **Ready** (not **Checking configuration…** or **Updating configuration…**).
* On self-hosted, complete the **Slack app** and **AI model** sections before saving.
* Resolve any **AI model check failed** or Slack credential error shown next to the button or under a field in the drawer.

### AI model check failed

These messages come from Nebuly verifying your provider, model, and API key. After a failed **Save and enable**, field-specific errors appear under the matching control; other failures appear next to **Add to Slack**. If a key is revoked after setup, the same text may appear in the status line when Nebuly polls configuration.

| Message | Shown under | What to do |
| - | - | - |
| Invalid API key | **Key** | Confirm the key belongs to the selected **Provider** and is active. |
| Model not found for this provider | **Model** | Check the model ID against the provider's model list (use **Model list** in the drawer). |
| Rate limit or quota exceeded for this key | Status line | Check billing or usage limits on the key. |
| Provider is unavailable, try again later | Status line | Retry after the provider recovers. |
| Could not reach the provider, try again later | Status line | Check network egress from your deployment (self-hosted) or retry. |
| Provider rejected the request (HTTP …) | Status line | Check the provider account and model access. |

### Slack app errors when saving

A wrong **Client secret** may not stop Nebuly AI agent from answering in workspaces that were already installed (the bot uses saved bot tokens and Socket Mode). It still breaks **Add to Slack** and new installs until the secret is fixed.

| Message | Shown under | What to do |
| - | - | - |
| Slack Client ID must look like 1234567890.1234567890 | **Client ID** | Copy **Client ID** from Slack app → Basic Information. |
| Slack doesn't recognize this Client ID | **Client ID** | Confirm **Client ID** matches the Slack app you created. |
| Client secret is required | **Client secret** | Paste the app **Client secret** from Basic Information. |
| Enter the Client secret for this Client ID | **Client secret** | Paste the **Client secret** for the **Client ID** you entered (required when you change **Client ID**). |
| Slack rejected this Client secret | **Client secret** | Copy the **Client secret** from Basic Information again; it must match this **Client ID**. |
| Slack rejected these credentials (…) | **Client secret** | See the Slack error code; fix **Client ID** and **Client secret** in api.slack.com. |
| App token is required | **App token** | Paste an app-level token (`xapp-…`). |
| App token must start with xapp- | **App token** | Use an app-level token, not a bot or user token. |
| Slack rejected this app token, generate a new one | **App token** | Regenerate the token in Slack and paste it again. |
| Use an app-level token (xapp-…), not a bot or user token | **App token** | Create an app-level token under Basic Information → App-Level Tokens. |
| App token needs the connections:write scope | **App token** | Regenerate with scope **connections:write**. |
| Slack rejected this app token (…) | **App token** | See the Slack error code in parentheses; fix the token in api.slack.com. |
| Could not reach Slack, try again later | **App token** | Retry; check network egress from your deployment. |

### App can't be installed in this workspace

* Use **Add to Slack** from your Nebuly environment or the correct install URL for your deployment (not another tenant's link).
* On self-hosted, confirm `BOT_URL` and OAuth redirect URLs match the Slack app manifest.

### Connect Nebuly fails

* Sign in with the same Nebuly account you use in the web app.
* Retry in a browser; confirm you approved the correct Slack workspace and user on the confirmation page.

### Nebuly AI agent does not reply in a channel

* Confirm the app is installed in the workspace and Nebuly AI agent is in the channel (`/invite @Nebuly AI agent`).
* Confirm you completed **Connect Nebuly** for your Slack user.
* Confirm the integration is **Enabled**, not **Disabled** or **Needs attention**.

### Nebuly AI agent does not remember an earlier answer

* Use **Share to channel** so follow-ups in the thread include context, or repeat the relevant details in your question.

### Wrong data

* Check the channel default with `/nebuly-project` and your Nebuly project permissions in the web app.

## What's next

* [MCP server](https://docs.nebuly.com/documentation/nebuly-ai/mcp-server.md) — connect other assistants to the same Nebuly data.
* [Microsoft Copilot](https://docs.nebuly.com/documentation/nebuly-ai/microsoft-copilot.md) — publish a Copilot Studio agent with Nebuly MCP.


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