/setup-slack.en

description: "Lesson command"
duration: "~15 min"
prerequisites: ["Admin access to a Slack workspace"]
level: "beginner"
tags: ["setup", "slack", "api"]
nonInteractiveMode: incompatible

Slack API Setup

Step 0: Check Setup Progress

**What the AI auto-runs:** 1. Run `uv run python tools/setup_progress.py show --current setup-slack` to display progress 2. **This step is optional.** You can skip it if you won't be using Slack integration 3. Auto-detect existing token:

• Check whether `SLACK_USER_TOKEN` exists in `.env` or credential store
• If it exists, verify validity with Slack API `auth.test`. If valid, ask "Slack is already configured. Would you like to skip?"

4. If skipping: Run `uv run python tools/setup_progress.py skip setup-slack --reason 'User skipped'`

What You'll Do in This Session

| Item | Details | |------|---------| | Goal | Create a Slack App, obtain a User Token, save it securely, and enable Slack search and message retrieval features | | Duration | ~15 minutes | | Prerequisites | Admin access to a Slack workspace (or permission to add Apps), browser available | | Skill Level | No CLI commands needed (all auto-run by AI + GUI-only operations) |

**Session flow:** 1. Open the Slack App management page (AI auto-launches browser) 2. Create a new Slack App (click buttons on screen) 3. Set up User Token Scopes (add required permissions) 4. Install to workspace (click the allow button) 5. Save the User Token securely (using credential_manager) 6. Operation test (AI auto-runs)

> **Hint**: If the AI stops responding midway, type "please continue" or "it stopped" to resume.

---

Readiness Check

**AskQuestion configuration:**

{
  "title": "Pre-session confirmation",
  "questions": [{
    "id": "readiness",
    "prompt": "Are you ready?",
    "options": [
      {"id": "ready", "label": "Ready! Let's start"},
      {"id": "chrome", "label": "Automate browser operations with /chrome"},
      {"id": "check_prereq", "label": "I want to check the prerequisites"},
      {"id": "no_slack", "label": "I don't have a Slack workspace"},
      {"id": "different_lesson", "label": "Go to a different lesson"}
    ]
  }]
}

(ready -> Proceed to Step 1) (chrome -> After opening the browser in Step 1, follow the "Chrome integration automation" section) (check_prereq -> Guide: "You're good to go if you're logged into a Slack workspace and have permission to add Apps. If you don't have permission, check with your workspace admin") (no_slack -> Guide: "You can create a Slack workspace for free. Create a test workspace at https://slack.com/create, then restart this setup") (different_lesson -> Show module list)

---

Step 1: Open Slack App Management Page

**What the AI does:** 1. Auto-detect the OS (Mac / Windows / Linux) 2. Run the following command to auto-launch the browser:

# Mac:
open https://api.slack.com/apps
# Windows:
start https://api.slack.com/apps
# Linux:
xdg-open https://api.slack.com/apps

**Once the browser opens, display the following AskQuestion:**

{
  "title": "Step 1: Create a Slack App",
  "questions": [{
    "id": "app_create",
    "prompt": "The Slack App management page has opened in your browser. Follow these steps to create a new App:\n\n1. Click the 'Create New App' button in the top right\n2. Select 'From scratch'\n3. Enter 'AIAgent Bootcamp' as the App Name\n4. Select your workspace under 'Pick a workspace'\n5. Click the 'Create App' button\n\nWere you able to create the App?",
    "options": [
      {"id": "created", "label": "App created!"},
      {"id": "browser_not_open", "label": "The browser didn't open"},
      {"id": "no_create_button", "label": "Can't find the 'Create New App' button"},
      {"id": "no_workspace", "label": "My workspace doesn't appear"},
      {"id": "permission_error", "label": "I got a permissions error"}
    ]
  }]
}

(created -> Proceed to Step 2) (browser_not_open -> Guide: "Please open this URL directly in your browser: https://api.slack.com/apps") (no_create_button -> Guide: "You may not be logged in to Slack. First, click 'Sign in' in the top right to log in with your Slack account") (no_workspace -> Guide: "Reload the page while logged into your workspace. If it still doesn't appear, you may need to create a new workspace") (permission_error -> Guide: "Your workspace admin may have restricted App additions. Ask the admin to allow adding a Slack App called 'AIAgent Bootcamp'. Alternatively, create a free test workspace at https://slack.com/create")

---

Chrome Integration Automation (`/chrome` mode)

**Prerequisites:** The "Claude in Chrome" extension (v1.0.36+) is installed in Chrome, and you launched with `claude --chrome` or ran `/chrome` within the session.

**What the AI auto-runs via Chrome integration:** 1. Open https://api.slack.com/apps in the browser 2. Use Chrome integration to sequentially perform:

• Click "Create New App"
• Select "From scratch"
• Enter "AIAgent Bootcamp" as the App Name
• Select a workspace under "Pick a workspace"
• Click "Create App"
• Click "OAuth & Permissions" in the left menu
• In the "User Token Scopes" section, click "Add an OAuth Scope" and add these 4 scopes one by one: channels:history, channels:read, chat:write, users:read
• Click "Install to Workspace" at the top of the page
• Click "Allow" on the permission confirmation screen

3. Once the User OAuth Token (xoxp-...) appears, prompt the user: "Click the Copy button next to the token to copy it" 4. Proceed to Step 4

**Note:** Do not read the token value from the browser screen. The user copies it manually.

If Chrome integration is not available, follow the manual steps in Steps 2-3 below.

---

Step 2: Set Up User Token Scopes

**AskQuestion configuration:**

{
  "title": "Step 2: Set Up User Token Scopes",
  "questions": [{
    "id": "scope_setup",
    "prompt": "The App settings page is displayed. Follow these steps to set up User Tok