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.mdindex 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 |---