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

# Slack setup

ConfigView pulls Slack data through Slack apps that you create in your own account. Depending on your Slack plan, you may need **one or two separate apps**:

| App                                  | Required for                                                                                                                                       | Plans                          |
| ------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------ |
| **ConfigView** (workspace app)       | Users, channels, user groups, custom emoji, files, channel membership, the `/configview` slash command                                             | All Slack plans                |
| **ConfigView Admin** (org-level app) | Workspaces inventory, per-workspace user membership, approved/restricted apps, app scopes, role assignments, information barriers, invite requests | **Slack Enterprise Grid only** |

The two apps are intentionally separate because they install differently — the workspace app is installed per workspace and uses a bot token (`xoxb-...`), while the org-level app must be installed by an **Org Owner** across the entire Enterprise Grid and uses a user token (`xoxp-...`) with admin scopes that are not available to workspace-scoped apps.

If you are on a single workspace plan, do Part 1 only. If you are on Enterprise Grid, do Parts 1 and 2. Part 3 (the `/configview` slash command) is optional and only needs the Part 1 app.

***

## Part 1: Slack Workspace Ingestion

Set up the **ConfigView** workspace app so ConfigView can pull your workspace data (users, channels, user groups, custom emoji, recent files) into the dashboard.

***

### Step 1: Create the ConfigView Slack App

1. Go to: [https://api.slack.com/apps](https://api.slack.com/apps)
2. Click **Create New App**
3. Choose **From scratch**
4. **App Name:** `ConfigView`
5. Pick your **workspace** from the dropdown
6. Click **Create App**

***

### Step 2: Add Bot Token Scopes

1. In the left sidebar, click **OAuth & Permissions**
2. Scroll down to **Scopes** > **Bot Token Scopes**
3. Click **Add an OAuth Scope** and add each of the following:

| Scope              | Purpose                                         |
| ------------------ | ----------------------------------------------- |
| `users:read`       | Read workspace member profiles                  |
| `users:read.email` | Read member email addresses                     |
| `channels:read`    | List public channels and their membership       |
| `groups:read`      | List private channels the bot is in             |
| `usergroups:read`  | List user groups and their members              |
| `emoji:read`       | List custom workspace emoji                     |
| `files:read`       | List recent files (governance / DLP visibility) |

***

### Step 3: Install the App to Your Workspace

1. Scroll to the top of **OAuth & Permissions**
2. Click **Install to Workspace**
3. Review the permissions and click **Allow**
4. Copy the **Bot User OAuth Token** (starts with `xoxb-`)

> Keep this token safe. You will add it to ConfigView in the next step.

***

### Step 4: Add the Token to ConfigView

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/secret/`
2. Click **Add Secret**
3. **Secret name:** `SLACK_BOT_TOKEN`
4. **Secret value:** Paste the `xoxb-...` token you copied
5. Click **Save**

***

### Step 5: Enable the Workspace Scripts in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`

2. You should see **Slack** in the list of available apps

3. Select the scripts you want to run:
   * **Users** — All workspace members with email, admin status, 2FA, timezone
   * **Channels** — Public and private channels with member counts
   * **Channel Members** — Which users are in which channels
   * **User Groups** — Handle-based groups (e.g. `@engineering`)
   * **User Group Members** — Which users belong to which groups
   * **Custom Emoji** — All custom workspace emoji
   * **Files (recent)** — Files uploaded in the last 7 days
   * **Bots** — Bot user accounts and the apps that own them

4. Click **Save**

> **Note:** Channel Members depends on Channels; User Group Members depends on User Groups; Bots depends on Users. ConfigView wires these dependencies automatically — parent scripts always run first.

***

### Step 6: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **Slack** health check
3. The workspace section should pass:
   * Secret Manager: `SLACK_BOT_TOKEN`
   * Slack bot auth
   * `users.list` scope (`users:read`)
   * `users:read.email` scope
   * `conversations.list` scope (`channels:read` + `groups:read`)
   * `usergroups.list` scope (`usergroups:read`)
   * `emoji.list` scope (`emoji:read`)
   * `files.list` scope (`files:read`)

If a check fails, verify:

* The `SLACK_BOT_TOKEN` secret is saved correctly (no extra spaces)
* The bot has been installed to the correct workspace
* All scopes from Step 2 were added before installing

> The admin sections of the health check will show `Skipped` until you complete Part 2. That is expected on non-Enterprise plans.

***

### Workspace Data Tables

| Table                      | Key Columns                                                          |
| -------------------------- | -------------------------------------------------------------------- |
| `slack_users`              | slack\_user\_id, email, real\_name, is\_admin, has\_2fa, deleted     |
| `slack_channels`           | channel\_id, name, is\_private, is\_archived, num\_members, creator  |
| `slack_channel_members`    | channel\_id, slack\_user\_id                                         |
| `slack_user_groups`        | group\_id, name, handle, user\_count                                 |
| `slack_user_group_members` | group\_id, slack\_user\_id                                           |
| `slack_emoji`              | name, is\_alias, alias\_for, url                                     |
| `slack_files`              | file\_id, name, mimetype, size\_bytes, user\_id, is\_public, created |
| `slack_bots`               | slack\_user\_id, bot\_id, app\_id, name, team\_id, deleted           |

All tables include a `run_at` column for historical tracking.

***

## Part 2: Slack Enterprise Grid Admin Ingestion

> **Skip this section if you are not on Slack Enterprise Grid.** The endpoints below only work on Enterprise Grid plans and require admin scopes that are not available to workspace-scoped apps.

This part covers a **separate, second Slack app** installed at the **Enterprise Grid org level** by an **Org Owner**. It pulls org-wide governance data: every workspace, per-workspace user membership, approved/restricted apps and their OAuth scopes, role assignments, information barriers, and invite requests.

You cannot add these admin scopes to the workspace app from Part 1 — admin scopes only become available when the app is created and installed at the org level.

***

### Step 1: Create the ConfigView Admin Slack App

1. Sign in to Slack as an **Org Owner** (this is required to see org-level options)
2. Go to: [https://api.slack.com/apps](https://api.slack.com/apps)
3. Click **Create New App**
4. Choose **From scratch**
5. **App Name:** `ConfigView Admin`
6. Pick your **Enterprise Grid org** from the dropdown (not an individual workspace)
7. Click **Create App**

> If the dropdown only shows individual workspaces and not your org, you are not signed in as an Org Owner. Contact your Slack admin to either sign in themselves or grant you Org Owner privileges.

***

### Step 2: Add User Token Scopes (Admin)

1. In the left sidebar, click **OAuth & Permissions**
2. Scroll down to **Scopes** > **User Token Scopes** (not Bot Token Scopes)
3. Click **Add an OAuth Scope** and add each of the following:

| Scope                      | Used by                                                  |
| -------------------------- | -------------------------------------------------------- |
| `admin.teams:read`         | Workspaces inventory + workspace admins                  |
| `admin.users:read`         | Per-workspace user membership                            |
| `admin.apps:read`          | Approved apps, restricted apps, app requests, app scopes |
| `admin.conversations:read` | Org-wide conversations inventory                         |
| `admin.roles:read`         | Role assignments (admin / owner / etc.)                  |
| `admin.barriers:read`      | Information barriers                                     |
| `admin.usergroups:read`    | User group → channel mappings                            |
| `admin.invites:read`       | Pending invite requests                                  |

> This app does **not** need any bot token scopes. The admin endpoints are user-token-only.

***

### Step 3: Install at the Org Level

1. Scroll to the top of **OAuth & Permissions**
2. Click **Install to Organization** (the wording will say "Organization", not "Workspace", because you created the app at the org level)
3. Review the admin permissions and click **Allow**
4. Copy the **User OAuth Token** (starts with `xoxp-`)

> **Note:** The token is a *user* token tied to whichever Org Owner installs the app. If that person leaves the company, the token may stop working. Use a dedicated service account (an Org Owner account owned by IT, not a personal account) wherever possible.

***

### Step 4: Add the Admin Token to ConfigView

1. Go to: `https://{companyname}.configview.com/admin/secret/`
2. Click **Add Secret**
3. **Secret name:** `SLACK_ADMIN_USER_TOKEN`
4. **Secret value:** Paste the `xoxp-...` token you copied
5. Click **Save**

> Both `SLACK_BOT_TOKEN` (from Part 1) and `SLACK_ADMIN_USER_TOKEN` need to coexist. The Slack scripts pick whichever token the endpoint requires.

***

### Step 5: Enable the Admin Scripts in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`

2. In the **Slack** section, enable the additional admin scripts:
   * **Workspaces (Admin)** — Every workspace in the Enterprise Grid org
   * **Workspace Admins** — Which users are admins of each workspace
   * **Org Users (per Workspace)** — User-to-workspace membership matrix
   * **Approved Apps** — Apps approved org-wide or per workspace, with their OAuth scopes
   * **Restricted Apps** — Apps explicitly restricted org-wide or per workspace
   * **App Requests** — Pending install requests
   * **App Scopes** — Normalized table of every (app, scope) pair, with sensitivity flag
   * **Conversations (Org-wide)** — Channels visible across the entire org
   * **Role Assignments** — Admin/Owner/etc. role grants
   * **Information Barriers** — Configured barriers between user groups
   * **User Group Channels** — Channels each user group is auto-added to
   * **Invite Requests** — Pending invitations awaiting approval

3. Click **Save**

> Most admin scripts depend on **Workspaces (Admin)** so the org's workspace list is available to iterate. App Scopes depends on Approved Apps + Restricted Apps. ConfigView handles all of this automatically.

***

### Step 6: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **Slack** health check
3. The admin section should now pass:
   * Secret Manager: `SLACK_ADMIN_USER_TOKEN`
   * Slack admin auth
   * `admin.teams.list` scope (`admin.teams:read`)
   * `admin.users.list` scope (`admin.users:read`)
   * `admin.apps.approved.list` scope (`admin.apps:read`)
   * `admin.apps.restricted.list` scope (`admin.apps:read`)
   * `admin.apps.requests.list` scope (`admin.apps:read`)
   * `admin.conversations.search` scope (`admin.conversations:read`)
   * `admin.roles.listAssignments` scope (`admin.roles:read`)
   * `admin.barriers.list` scope (`admin.barriers:read`)
   * `admin.usergroups.listChannels` scope (`admin.usergroups:read`)
   * `admin.inviteRequests.list` scope (`admin.invites:read`)

If a scope check fails, the most common cause is that the scope was added in **Bot Token Scopes** rather than **User Token Scopes**. Re-check Step 2, then **reinstall to the organization** for the change to take effect.

***

### Tuning: Files window

The **Files (recent)** script (Part 1) defaults to the last 7 days. If you want a wider or narrower window, set the environment variable on the server:

```
SLACK_FILES_WINDOW_DAYS=30
```

Larger windows produce significantly more rows; start at 7 and widen only if needed.

***

### Admin Data Tables

| Table                            | Key Columns                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------- |
| `slack_admin_teams`              | team\_id, name, domain, email\_domain, is\_verified, date\_created                       |
| `slack_admin_team_admins`        | team\_id, slack\_user\_id                                                                |
| `slack_admin_users`              | slack\_user\_id, team\_id, email, is\_active, is\_admin, has\_2fa, datetime\_last\_login |
| `slack_admin_apps_approved`      | app\_id, app\_name, team\_id, scope\_type, scopes\_json, date\_updated                   |
| `slack_admin_apps_restricted`    | app\_id, app\_name, team\_id, scope\_type, scopes\_json, date\_updated                   |
| `slack_admin_apps_requests`      | request\_id, app\_id, requester\_email, team\_id, message, date\_created                 |
| `slack_admin_app_scopes`         | state (approved/restricted), app\_id, scope\_name, is\_sensitive, token\_type            |
| `slack_admin_conversations`      | channel\_id, name, conversation\_type, member\_count, is\_org\_shared, is\_ext\_shared   |
| `slack_admin_roles_assignments`  | role\_id, entity\_type, entity\_id, user\_id                                             |
| `slack_admin_barriers`           | barrier\_id, primary\_usergroup\_id, barriered\_from\_usergroup\_ids\_json               |
| `slack_admin_usergroup_channels` | usergroup\_id, channel\_id, team\_id                                                     |
| `slack_admin_invite_requests`    | request\_id, email, team\_id, requester\_user\_id, date\_created                         |

All tables include a `run_at` column for historical tracking.

***

## Part 3: Slack Bot (Query Runner)

Run ConfigView queries directly from Slack using the `/configview` slash command. This uses the **ConfigView workspace app** from Part 1, not the admin app.

***

### Step 1: Add Bot Scopes

1. Go back to: [https://api.slack.com/apps](https://api.slack.com/apps)
2. Select your **ConfigView** app (the workspace app from Part 1)
3. Go to **OAuth & Permissions** > **Bot Token Scopes**
4. Add the following additional scopes:

| Scope        | Purpose                   |
| ------------ | ------------------------- |
| `chat:write` | Post messages to channels |
| `commands`   | Enable slash commands     |

5. You will be prompted to **reinstall** the app. Click **Reinstall to Workspace** and approve.

> **Important:** After reinstalling, the bot token stays the same. You do not need to update the secret in ConfigView.

***

### Step 2: (Optional) Add Signing Secret

The signing secret lets ConfigView verify that incoming requests are genuinely from Slack.

1. In your Slack app settings, go to **Basic Information**
2. Scroll to **App Credentials**
3. Copy the **Signing Secret**
4. In ConfigView, go to `https://{companyname}.configview.com/admin/secret/`
5. Add a secret: **Name:** `SLACK_SIGNING_SECRET`, **Value:** paste the signing secret

> This is optional but recommended for production use.

***

### Step 3: Enable the Slash Command

1. In the left sidebar, click **Slash Commands**
2. Click **Create New Command**
3. Fill in:
   * **Command:** `/configview`
   * **Request URL:** `https://{companyname}.configview.com/api/slack/command`
   * **Short Description:** `Run ConfigView queries`
   * **Usage Hint:** `[help | run <query_id>]`
4. Click **Save**

***

### Step 4: Enable Interactivity

This lets users click the "Run" buttons in the query list.

1. In the left sidebar, click **Interactivity & Shortcuts**
2. Toggle **Interactivity** to **On**
3. Set **Request URL** to: `https://{companyname}.configview.com/api/slack/interaction`
4. Click **Save Changes**

***

### Step 5: Invite the Bot to a Channel

1. Open the Slack channel where you want the bot to post (e.g. `#configview-alerts`)
2. Type: `/invite @ConfigView`

> Create a dedicated channel like `#configview-alerts` to keep query results organized.

***

### Step 6: Mark Queries as Slack-Enabled

1. Go to: `https://{companyname}.configview.com/admin/query/`
2. Open a saved query and click **Save**
3. Toggle **Enable for Slack bot** to on
4. Fill in the **Slack summary** — this is the description users see when browsing queries in Slack
5. Click **Save**

***

### Step 7: Test It

1. Open the Slack channel where the bot was invited
2. Type: `/configview`
3. You should see a list of slack-enabled queries with **Run** buttons
4. Click **Run** on a query — the bot posts the results to the channel

You can also run a query directly by ID:

```
/configview run 42
```

Or get help:

```
/configview help
```

***

### Bot Commands

| Command                | Action                                          |
| ---------------------- | ----------------------------------------------- |
| `/configview`          | List all slack-enabled queries with Run buttons |
| `/configview run <id>` | Run a specific query by ID and post results     |
| `/configview help`     | Show available commands                         |

***

### Message Format

The bot posts formatted messages with:

* **Query name** as the header
* **Row count** summary
* **Table** of results (up to 10 rows, 6 columns)
* Truncation notice if results exceed the display limit

***

### Troubleshooting

| Issue                                         | Fix                                                                                                                                                                                                                         |
| --------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `/configview` says "not found"                | Verify the Slash Command Request URL matches your ConfigView domain                                                                                                                                                         |
| Bot posts nothing on button click             | Check the Interactivity Request URL is correct                                                                                                                                                                              |
| "channel\_not\_found" error                   | Verify the channel name — no `#` prefix, exact spelling                                                                                                                                                                     |
| "not\_in\_channel" error                      | The bot must be invited to private channels with `/invite @ConfigView`                                                                                                                                                      |
| "not\_authed" or "invalid\_auth"              | Verify `SLACK_BOT_TOKEN` secret is correct in ConfigView                                                                                                                                                                    |
| Query results are empty                       | Check that the query works in the ConfigView Query page first                                                                                                                                                               |
| Messages stop after app reinstall             | Token should persist, but re-check `SLACK_BOT_TOKEN` if issues occur                                                                                                                                                        |
| Admin scripts return `not_allowed_token_type` | The endpoint needs a user token. Verify you used `SLACK_ADMIN_USER_TOKEN` (Part 2), not `SLACK_BOT_TOKEN`                                                                                                                   |
| Admin scripts return `missing_scope`          | Add the scope listed in Part 2 Step 2 under **User Token Scopes**, then reinstall the admin app to the organization                                                                                                         |
| Admin scripts return `not_an_enterprise`      | The org-level app isn't installed on Enterprise Grid. Either the customer isn't on Enterprise Grid (skip Part 2 entirely) or the app was created against a single workspace instead of the org — recreate per Part 2 Step 1 |