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

# Slack

> Query your data directly from Slack using @mentions, DMs, and the Oxygen assistant sidebar

The Oxygen Slack app lets your team ask data questions without leaving Slack. Mention `@Oxygen` in any channel or send it a direct message — it runs your query, streams the answer, and posts a formatted response with charts and a **View thread in Oxygen** link for the full conversation.

## Prerequisites

* An Oxygen Cloud account with at least one workspace configured
* Owner or Admin role in the Oxygen org
* Admin permissions in the target Slack workspace

## Installation

<Steps>
  <Step title="Open Org Settings">
    In the Oxygen web app, navigate to **Org Settings → Integrations**.
  </Step>

  <Step title="Install to Slack">
    Click **Install to Slack**. You are redirected to Slack's OAuth screen.
  </Step>

  <Step title="Authorise Oxygen">
    Review the permissions and click **Allow**. Slack redirects you back to Oxygen. The Integrations tab confirms the connected workspace name.
  </Step>

  <Step title="Invite the bot to a channel">
    In Slack, type `/invite @Oxygen` in any channel where you want to use it. In DMs, no invite is needed — just open the Oxygen app and start typing.
  </Step>
</Steps>

<Info>
  Only **Owner** and **Admin** org roles can install or disconnect the Slack app. All members can use it once it is installed.
</Info>

***

## Connecting Your Account

The first time you message `@Oxygen`, it checks whether your Slack email matches an existing Oxygen account in the org. If it does, you are linked automatically and your question runs immediately.

If automatic matching fails (different email, SSO, or guest account), Oxygen sends an ephemeral prompt only you can see:

> 🔗 **Connect your Oxygen account**\
> To query your data from Slack, connect your Oxygen account first. This takes less than a minute.\
> **\[ Connect to Oxygen → ]**

Click the button, confirm in the browser, and Oxygen replies:

> ✅ **You're connected!** Go back and ask your question — I'm ready.

From then on, your Slack account is automatically linked. No further action needed.

<Info>
  If you don't complete the link, Oxygen shows the prompt again on your next message. Keep asking — the link stays open until you confirm it.
</Info>

***

## Asking Questions

### @Mention in a channel

```
@Oxygen what was revenue last month broken down by region?
```

Oxygen replies in the same thread. Only you see workspace-picker prompts or error messages.

### Direct message

Open the Oxygen app in your DM list and type directly — no @mention needed. Follow-ups in the same DM thread continue the conversation automatically.

### AI Assistant sidebar

Oxygen supports Slack's native AI Assistant sidebar. Click the sparkle icon in any channel header to open the assistant panel. Oxygen surfaces starter prompts when you begin a new thread.

***

## Selecting a Workspace

If your org has multiple Oxygen workspaces, a picker appears the first time you ask in a channel:

> **Select a workspace** ▾\
> ☐ Set as default for this channel\
> **\[ Select ]**

Checking **Set as default for this channel** skips the picker automatically for future questions in that channel. You can change or clear the default at any time from **Oxygen App Home → Settings**.

***

## Reading Responses

Oxygen responses include:

| Element                     | Description                                                                                  |
| --------------------------- | -------------------------------------------------------------------------------------------- |
| **Answer**                  | Prose streamed as the agent writes it                                                        |
| **Charts**                  | Rendered inline when image hosting is configured; otherwise a link opens the chart in Oxygen |
| **View thread in Oxygen →** | Opens the full conversation — SQL, data tables, follow-up history                            |
| **Wrong workspace?**        | Re-opens the workspace picker to re-run against a different workspace                        |

***

## Error Messages

### "🔗 Connect your Oxygen account"

Your Slack account is not linked yet. Click **Connect to Oxygen →** and confirm in the browser. See [Connecting Your Account](#connecting-your-account).

### "You're no longer a member of this Oxygen org"

Your Oxygen account was removed from the org after your Slack account was linked. Ask an org admin to re-invite you.

### "No workspaces available"

Your Oxygen account doesn't have access to any workspaces, or the org has none configured yet. Contact your Oxygen admin.

### "Workspace X has no agents configured"

The selected workspace has no `.agent.yml` files. Add at least one agent to the workspace and try again.

### "Something went wrong"

An unexpected server error occurred. If a **View thread in Oxygen →** button appears, click it to see what was partially computed. Retry after a moment. If the problem persists, check the Oxygen server logs.

***

## Chart Image Publishing

Charts produced by Oxygen render to PNG and upload directly to Slack via [`files.uploadV2`](https://docs.slack.dev/reference/methods/files.uploadV2). The image lives inside Slack — no presigned URLs, no expiration, no separate object store. Each chart appears as an inline Block Kit `image` block in the answer.

Set this on your Oxygen server to enable the upload path:

| Variable                 | Required         | Description                                                                                                                                                                                                                                                 |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `OXY_SLACK_CHART_UPLOAD` | Yes (production) | Set to `1` (or `true`) to upload charts to Slack. When unset, charts render to local disk and surface as a context-block breadcrumb — Slack can't fetch a localhost path so there is no inline preview. The default-off behavior matches local development. |

The bot needs the `files:write` scope (already present in the manifest). Existing installations that pre-date this change must reauthorize the app once for the new scope to take effect; subsequent chart uploads use the same bot token.

<Info>
  **Failure handling.** Each upload runs in parallel with a 15-second timeout; one chart failing does not block the rest of the answer. If any uploads fail, the message still posts and a footer reads "⚠️ N chart uploads failed — view in Oxygen →" so the user can fall back to the in-app chart, which renders client-side via echarts.
</Info>

<Note>
  Files uploaded this way count toward the workspace's Slack file storage. They are visible to anyone with access to the channel where the answer was posted, matching Slack's normal file-sharing semantics.
</Note>

***

## Disconnecting

1. Go to **Org Settings → Integrations** in the Oxygen web app.
2. Click **Disconnect** next to the Slack workspace.

This revokes the bot token and removes all stored installation data. Existing Slack threads remain visible but the bot will no longer respond. To reconnect, follow the [Installation](#installation) steps again.

***

## Permissions

Oxygen requests the following Slack scopes:

| Scope               | Purpose                                               |
| ------------------- | ----------------------------------------------------- |
| `chat:write`        | Post answers and ephemeral messages                   |
| `app_mentions:read` | Receive @mention events                               |
| `files:write`       | Upload rendered chart PNGs into the answer thread     |
| `im:history`        | Read DMs sent to Oxygen                               |
| `im:write`          | Send DM confirmations                                 |
| `assistant:write`   | Use the AI Assistant sidebar                          |
| `users:read.email`  | Auto-match Slack accounts to Oxygen accounts by email |
| `channels:history`  | Read thread context for follow-up questions           |

Oxygen reads **only** messages directed at it (via @mention, DM, or the assistant sidebar). It does not monitor general channel history.