Slack

This guide walks you through creating a Slack app and connecting it to OpenACP. Each coding session gets its own dedicated Slack channel, keeping conversations isolated and easy to search.

Prerequisites

• Slack workspace admin access — required to create and install an app

• OpenACP installed: npm install -g @openacp/cli

• At least one ACP agent installed (e.g., claude-agent-acp)

---

Step 1: Create a Slack App

1. Go to api.slack.com/apps.

2. Click Create New App.

3. Choose From scratch.

4. Enter a name (e.g., OpenACP).

5. Select your Slack workspace.

6. Click Create App.

You are now on the app's Basic Information page. Keep this page open — you will return to it several times.

---

Step 2: Enable Socket Mode and Generate an App-Level Token

OpenACP uses Socket Mode to connect to Slack over a persistent WebSocket connection. This means no public URL or webhook is required — ideal for running on a local machine.

1. In the left sidebar, go to Socket Mode.

2. Toggle Enable Socket Mode to On.

3. A dialog prompts you to create an App-Level Token. Click Generate Token and Events.

4. Name the token (e.g., openacp-token).

5. Under Scopes, select connections:write.

6. Click Generate.

7. Copy and save the token — it starts with xapp-1-.... You will need it as appToken in the OpenACP config.

This token controls your app's WebSocket connection. Store it securely and do not commit it to version control.

---

Step 3: Configure Bot Token Scopes

Bot Token Scopes determine what your bot is allowed to do in the workspace.

1. In the left sidebar, go to OAuth & Permissions.

2. Scroll down to Bot Token Scopes.

3. Click Add an OAuth Scope and add each of the following:

Scope	Why it is needed
chat:write	Post messages in session channels
chat:write.public	Post in channels without joining them first
channels:history	Receive message events from public channels (required — without this, messages are silently dropped)
channels:manage	Create and archive public session channels
channels:read	List and inspect channels
channels:join	Join channels when needed
groups:history	Receive message events from private channels (required — without this, messages are silently dropped)
groups:read	List private channels
groups:write	Manage private channels
im:history	Receive direct messages
im:read	Read DM channel info
im:write	Open DM channels
users:read	Look up user information
files:read	Download uploaded files (required for voice message transcription)
files:write	Upload audio files (required for TTS voice replies)
commands	Register and handle slash commands
reactions:write	Add emoji reactions as status indicators

Important: channels:history and groups:history are critical. Without them, your bot connects via Socket Mode and joins channels successfully, but Slack silently drops all incoming message events — no errors and no logs. This is one of the most common sources of confusion during setup.

---

Step 4: Install the App to Your Workspace

1. In the left sidebar under Settings, go to Install App.

2. Click Install to Workspace.

3. Review the requested permissions.

4. Click Allow.

5. You are redirected to a page showing your Bot User OAuth Token.

6. Copy and save this token — it starts with xoxb-.... You will need it as botToken in the OpenACP config.

---

Step 5: Subscribe to Bot Events

After configuring scopes, subscribe to the message events OpenACP needs to receive.

1. In the left sidebar, go to Event Subscriptions.

2. Toggle Enable Events to On.

3. Scroll to Subscribe to bot events.

4. Click Add Bot User Event and add:

   • message.channels — receive messages from public channels the bot is in

   • message.groups — receive messages from private channels the bot is in

   • message.im — receive direct messages

   • app_mention — receive messages where the bot is @mentioned

5. Click Save Changes.

6. A banner prompts you to reinstall the app. Click Reinstall App (or go to Install App → Reinstall to Workspace).

In Socket Mode, event payloads are delivered over the WebSocket connection — no public URL is needed. However, you must still subscribe to the events here for Slack to deliver them to your app.

---

Step 6: Enable Interactivity

Permission buttons (Allow / Deny) require interactivity to be enabled.

1. In the left sidebar, go to Interactivity & Shortcuts.

2. Toggle Interactivity to On.

3. In Socket Mode, interactive payloads are delivered over the same WebSocket connection. Leave the Request URL field blank or set a placeholder value — it is not used in Socket Mode.

4. Click Save Changes.

---

Step 7: Get the Signing Secret

1. In the left sidebar, go to Basic Information.

2. Scroll down to App Credentials.

3. Copy the Signing Secret. You will need it as signingSecret in the OpenACP config.

---

Step 8: Configure OpenACP

Edit ~/.openacp/config.json and add the Slack section (see the full configuration reference for all available options):

{
  "channels": {
    "slack": {
      "enabled": true,
      "adapter": "slack",
      "botToken": "xoxb-...",
      "appToken": "xapp-1-...",
      "signingSecret": "abcd1234efgh5678ijkl9012",
      "notificationChannelId": "C1234567890",
      "allowedUserIds": [],
      "channelPrefix": "openacp"
    }
  }
}

Field	Description
enabled	Set to true to activate the Slack adapter
adapter	Must be "slack"
botToken	Bot User OAuth Token from Step 4 (starts with xoxb-)
appToken	App-Level Token from Step 2 (starts with xapp-1-)
signingSecret	Signing Secret from Step 7
notificationChannelId	Optional. Slack channel ID for system notifications. Right-click a channel → View Details → copy the ID from the URL (e.g., C1234567890)
allowedUserIds	Optional. Array of Slack user IDs allowed to create sessions. If empty, all workspace members can create sessions. Get a user's ID by opening their profile → click the ••• menu → Copy user ID
channelPrefix	Prefix for auto-created session channels. Default: openacp. Session channels are named {prefix}-{slug}-{sessionId}

---

Step 9: Start OpenACP and Test

Start OpenACP:

openacp start

Expected output:

[info] Slack bot authenticated (botUserId: U...)
[info] Slack adapter started (Socket Mode)

To create your first coding session, type the slash command in any Slack channel where the bot is present:

/new claude my-project

OpenACP creates a new channel named openacp-my-project-{id} and invites you to it.

---

How Sessions Work

Session Model

Each OpenACP session in Slack gets its own dedicated channel:

1. User sends /new [agent] [workspace] in any channel where the bot is present.

2. OpenACP creates a new channel named openacp-{slug}-{sessionId} (e.g., openacp-fix-auth-bug-a3k9).

3. The user sends coding requests in that session channel.

4. The agent responds with streaming text, tool call results, and code.

5. When the agent needs approval to run a command or edit a file, Allow and Deny buttons appear.

6. When the session ends or times out, the channel is archived for record-keeping.

Available Commands

Command	Description
/new [agent] [workspace]	Create a new session
/newchat	New session with the same agent and workspace as the current one
/cancel	Cancel the active session
/status	Show current session status or system status
/agents	List available agents
/help	Show help

Command Examples

/new claude my-app          → Claude session in ~/openacp-workspace/my-app/
/new codex api-server       → Codex session in ~/openacp-workspace/api-server/
/new claude ~/code/project  → Claude session at an absolute path
/new                        → Default agent and default workspace
/newchat                    → New session using current agent and workspace
/cancel                     → Cancel the running session

---

Voice Support (Speech-to-Text and Text-to-Speech)

The Slack adapter supports voice interactions — record audio clips and optionally receive spoken replies.

Speech-to-Text (STT)

Record an audio clip using Slack's built-in microphone button. OpenACP transcribes it using Groq Whisper (free tier: ~8 hours/day) and sends the transcribed text to the agent.

1. Get a free Groq API key at console.groq.com.

2. Add this to ~/.openacp/config.json:

{
  "speech": {
    "stt": {
      "provider": "groq",
      "providers": {
        "groq": {
          "apiKey": "gsk_..."
        }
      }
    }
  }
}

Or use environment variables:

export OPENACP_SPEECH_STT_PROVIDER=groq
export OPENACP_SPEECH_GROQ_API_KEY=gsk_...

1. Ensure your bot has the files:read scope (Step 3). If you added this scope after the initial install, reinstall the app to your workspace.

After restarting OpenACP, send an audio clip in a session channel. A transcription confirmation appears: 🎤 You said: ....

Text-to-Speech (TTS)

TTS uses Microsoft Edge TTS (free, no API key required). The agent's reply is synthesized into audio and uploaded as a playable file in the session channel.

Add this to ~/.openacp/config.json:

{
  "speech": {
    "tts": {
      "provider": "edge-tts"
    }
  }
}

Ensure your bot has the files:write scope (Step 3). Reinstall the app if this scope was added after initial installation.

---

Environment Variables

Override config values using environment variables:

export OPENACP_SLACK_BOT_TOKEN="xoxb-..."
export OPENACP_SLACK_APP_TOKEN="xapp-1-..."
export OPENACP_SLACK_SIGNING_SECRET="abcd1234..."
openacp start

Variable	Config path
OPENACP_SLACK_BOT_TOKEN	channels.slack.botToken
OPENACP_SLACK_APP_TOKEN	channels.slack.appToken
OPENACP_SLACK_SIGNING_SECRET	channels.slack.signingSecret

---

Troubleshooting

Messages are completely ignored (no response, no logs)

This is almost always a missing scope or event subscription.

1. Go to OAuth & Permissions → Bot Token Scopes and verify channels:history and groups:history are listed.

2. Go to Event Subscriptions → Subscribe to bot events and confirm message.channels and message.groups are listed.

3. After adding any new scope or event, you must reinstall the app to your workspace (Install App → Reinstall to Workspace).

"Socket Mode connection failed"

• Verify appToken starts with xapp-1-.

• Confirm Socket Mode is enabled in the app settings.

• Regenerate the App-Level Token if it may have expired.

Permission buttons not responding

• Go to Interactivity & Shortcuts and confirm Interactivity is toggled On.

• In Socket Mode, no Request URL is needed — interactive payloads arrive over the WebSocket.

Voice transcription returns "could not process file"

• The bot downloaded an HTML login page instead of the audio binary. This means the files:read scope is missing.

• Add files:read in OAuth & Permissions → Bot Token Scopes and reinstall the app.

"Bot is not a member of the channel"

• Verify the channels:join scope is enabled and reinstall the app.

"Invalid signing secret"

• Go to Basic Information → App Credentials and re-copy the Signing Secret. Ensure there are no leading or trailing spaces.

For more detailed troubleshooting, see Slack Issues.