From bf28877fec28949da84eb9bcc81a047ecddcef99 Mon Sep 17 00:00:00 2001 From: Jon Saad-Falcon <41205309+jonsaadfalcon@users.noreply.github.com> Date: Fri, 27 Mar 2026 22:12:36 -0700 Subject: [PATCH] docs: comprehensive Slack setup guide with Socket Mode, App Manifest, and troubleshooting Covers both data connector (read messages) and messaging channel (DM the agent). Includes the full App Manifest JSON, required scopes table, and all the gotchas we discovered (Request URL, reinstall requirement, App Token vs Bot Token, etc.). Co-Authored-By: Claude Opus 4.6 (1M context) --- docs/user-guide/channels-and-connectors.md | 105 +++++++++++++++++++-- 1 file changed, 95 insertions(+), 10 deletions(-) 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 | ---