Skip to content

Personal AI, On Personal Devices

Python

docs: comprehensive Slack setup guide with Socket Mode, App Manifest, and troubleshooting

Jon Saad-Falconbf28877fec28
diff --git a/docs/user-guide/channels-and-connectors.md b/docs/user-guide/channels-and-connectors.md
index 99ccd605..e3588ec1 100644
--- a/docs/user-guide/channels-and-connectors.md
+++ b/docs/user-guide/channels-and-connectors.md
@@ -120,36 +120,121 @@ Same as Google Drive — use the same Google Cloud project and OAuth client.
## Slack
-**What it indexes:** Channel messages and threads from your Slack workspace.
+Slack serves two purposes in OpenJarvis:
-### Setup
+- **Data connector** — indexes channel messages and threads so your agent can search them
+- **Messaging channel** — lets you DM your agent directly in Slack
+
+### Setup: Data Connector (read Slack messages)
1. **Go to Slack App Settings:**
[Open Slack Apps →](https://api.slack.com/apps)
-2. **Create a new app** (or use existing):
+2. **Create a new app:**
- Click "Create New App" → "From scratch"
- Name it (e.g. "OpenJarvis") and select your workspace
-3. **Add OAuth scopes:**
- - Go to "OAuth & Permissions"
- - Under "Bot Token Scopes", add: `channels:history`, `channels:read`, `users:read`
+3. **Add Bot Token Scopes** (OAuth & Permissions → Bot Token Scopes):
+
+ | Scope | Purpose |
+ |-------|---------|
+ | `chat:write` | Send messages |
+ | `im:write` | Open DM conversations |
+ | `im:read` | List DM conversations |
+ | `im:history` | Read DM history + receive DM events |
+ | `users:read` | Look up user info |
+ | `channels:read` | List public channels |
+ | `channels:history` | Read public channel messages |
+ | `app_mentions:read` | See @mentions of the bot |
4. **Install to workspace:**
- Click "Install to Workspace" → Authorize
- Copy the **Bot User OAuth Token** (starts with `xoxb-`)
5. **Connect in OpenJarvis:**
- - Desktop/Browser: Agents → Channels tab → Slack → paste the bot token
+ - Desktop/Browser: Agents → **Channels** tab → Slack → paste the bot token
- CLI: `uv run jarvis connect slack`
+### Setup: Messaging Channel (DM your agent in Slack)
+
+To DM your agent and get research responses, you need Socket Mode + Event Subscriptions:
+
+1. **Enable Socket Mode:**
+ - Go to your Slack app settings → **Socket Mode** (left sidebar)
+ - Toggle **"Enable Socket Mode"** to ON
+ - Click **"Generate"** to create an App-Level Token
+ - Add the `connections:write` scope
+ - Name it anything (e.g. "socket") → Generate
+ - Copy the token (starts with `xapp-`)
+
+2. **Set up Event Subscriptions:**
+ - Go to **App Manifest** (left sidebar) — this is the most reliable method
+ - Replace the entire manifest with:
+ ```json
+ {
+ "display_information": { "name": "OpenJarvis" },
+ "features": {
+ "app_home": {
+ "home_tab_enabled": true,
+ "messages_tab_enabled": true,
+ "messages_tab_read_only_enabled": false
+ },
+ "bot_user": { "display_name": "OpenJarvis", "always_online": true }
+ },
+ "oauth_config": {
+ "scopes": {
+ "bot": [
+ "chat:write", "im:write", "im:read", "im:history",
+ "users:read", "channels:read", "channels:history",
+ "app_mentions:read", "assistant:write"
+ ]
+ },
+ "pkce_enabled": false
+ },
+ "settings": {
+ "event_subscriptions": { "bot_events": ["message.im"] },
+ "org_deploy_enabled": false,
+ "socket_mode_enabled": true,
+ "token_rotation_enabled": false
+ }
+ }
+ ```
+ - Click **Save Changes**
+
+3. **Reinstall the app:**
+ - Go to **Install App** → click **"Reinstall to Workspace"**
+ - This is required after changing scopes or event subscriptions
+ - Copy the **new Bot User OAuth Token** (it may change after reinstall)
+
+4. **Connect in OpenJarvis:**
+ - Desktop/Browser: Agents → **Messaging** tab → Slack → Set Up
+ - Enter the **Bot Token** (`xoxb-...`) and **App Token** (`xapp-...`)
+ - Click Connect
+
+5. **DM your agent:**
+ - In Slack, find **OpenJarvis** under Apps (or Direct Messages)
+ - If you don't see it: click **"+"** next to Direct Messages → search "OpenJarvis"
+ - Send a message → the agent responds with "Message received! Researching now..." then the full research answer
+
+### Important Notes
+
+- **Reinstall after scope changes:** Every time you add new scopes or change event subscriptions, you MUST reinstall the app. Otherwise the changes don't take effect.
+- **Don't use the Event Subscriptions UI for Request URL:** With Socket Mode enabled, you don't need a Request URL. If the Event Subscriptions page asks for one, use the **App Manifest** method instead (step 2 above).
+- **App-Level Token vs Bot Token:** These are different. The Bot Token (`xoxb-`) is for API calls. The App Token (`xapp-`) is for Socket Mode. You need both for DMs to work.
+- **Thread replies:** If you reply in a thread, the bot sees it. New top-level messages also work.
+
### Troubleshooting
| Issue | Solution |
|-------|----------|
-| "not_allowed_token_type" | Make sure you're using the **Bot** token (`xoxb-...`), not a user token (`xoxp-`) or session token (`xoxe-`) |
-| No messages found | The bot can only see channels it's been added to. Invite it: `/invite @OpenJarvis` in the channel |
-| Missing private channels | Add `groups:history` and `groups:read` scopes, then reinstall the app |
+| "not_allowed_token_type" | Use the **Bot** token (`xoxb-...`), not a user token (`xoxp-`) or session token (`xoxe-`) |
+| "Sending messages to this app has been turned off" | Go to App Home → enable "Messages Tab" → check "Allow users to send messages from the messages tab" |
+| Bot doesn't respond to DMs | Make sure Socket Mode is enabled, `message.im` event is subscribed, and the app was reinstalled after changes |
+| "missing_scope" error | Add the missing scope in OAuth & Permissions → Reinstall the app |
+| Bot not visible in Slack | Go to Install App → Reinstall to Workspace |
+| No messages found (data connector) | The bot can only see channels it's been added to. Invite it: `/invite @OpenJarvis` in the channel |
+| Event Subscriptions won't save without Request URL | Use the App Manifest method instead (see step 2) — it bypasses the URL verification |
+| Socket Mode connects but no events received | Verify `message.im` is in the manifest's `bot_events`, reinstall the app |
---