Slack app setup

The onboarding flow generates a ready-made app manifest — it pre-configures every scope and event your agent needs. Use it so you don't have to click through 30+ checkboxes by hand.

1. In the onboarding form, enter your agent's name, then click Generate Slack manifest. The manifest is copied to your clipboard automatically.
2. Open api.slack.com/apps → Create New App and choose From a manifest.
3. Pick your workspace from the dropdown and click Next.
4. Select the JSON tab, clear the default content, and paste the manifest you just copied.
5. Review the scopes and events listed (they match what the agent uses — no extras), then click Create.

1. After the app is created, click Install to Workspace on the app's settings page (or from the banner at the top of the page) and click Allow.
2. In the left sidebar, go to OAuth & Permissions.
3. Copy the Bot User OAuth Token — it starts with xoxb-. This is what you paste into the Slack bot token field in the onboarding form.

Socket Mode keeps a persistent outbound WebSocket connection from your agent to Slack — no public webhook URL required. It needs a separate token with the connections:write scope.

1. In the left sidebar, go to Basic Information, then scroll to App-Level Tokens.
2. Click Generate Token and Scopes, give it any name (e.g. socket-mode), and add the scope connections:write.
3. Click Generate and copy the token — it starts with xapp-. This is the Slack App Token your Isomorph control plane needs during agent initialization.

The agent uses an allowlist to decide which Slack users it will respond to. You need the member ID for each person, not their display name. Member IDs look like U01ABC23DEF and never change even if a user renames themselves.

1. In Slack, click on any user's name to open their profile.
2. Click the ⋯ More (three-dot) menu and choose Copy member ID.
3. Paste the IDs (comma-separated) into the Whitelisted Slack user IDs field in the onboarding form.

The agent needs to be a member of the Slack channel it monitors. Once the app is installed and your agent is onboarded:

1. Open the channel you set as your agent's home channel.
2. Type /invite @your-agent-name and press Enter, or use the channel members panel to add the bot.

The agent's Slack display name matches the fork name you entered during onboarding.

You can update your app's name, bot scopes, and subscribed events at any time from the Slack app settings. Some changes require reinstalling the app before they take effect.

Renaming the app

1. Open your app at api.slack.com/apps and go to Basic Information.
2. Edit the App Name and Display Name fields, then click Save Changes. The name update takes effect immediately — no reinstall needed.

Adding or removing bot scopes

1. In the left sidebar, go to OAuth & Permissions and scroll to Scopes → Bot Token Scopes.
2. Click Add an OAuth Scope to add a scope, or the trash icon next to any existing scope to remove it.
3. After any scope change, Slack shows a banner: “You've changed the permission scopes…” Click Reinstall your app in that banner (or go to Install App in the sidebar) and click Allowagain. Slack issues a new bot token — copy it and update your agent's secret in AWS Secrets Manager.

Editing the full manifest directly

The quickest way to make several changes at once — name, scopes, events, and settings — is to edit the raw manifest:

1. In the left sidebar, go to App Manifest.
2. Edit the JSON directly. Key fields:
   • display_information.name — the app name shown in Slack
   • features.bot_user.display_name — the bot's @-handle display name
   • oauth_config.scopes.bot[] — the list of bot permission scopes
   • settings.event_subscriptions.bot_events[] — Slack events the bot receives
   • settings.socket_mode_enabled — must stay true for Socket Mode
3. Click Save Changes. If scopes changed, reinstall the app to get a new bot token as described above.

Both the bot token and the App-Level Token can be regenerated at any time. Do this if a token is compromised, if you reinstalled the app after a scope change, or as part of a routine credential rotation.

Rotate the bot token (xoxb-)

1. Go to OAuth & Permissions and click Revoke Token. This immediately invalidates the current token — your agent will lose Slack connectivity.
2. Click Reinstall to Workspace (or go to Install App → Install to Workspace) and click Allow. Slack issues a new bot token.
3. Copy the new xoxb-… token and update the argus/<tenant>/slack-bot-token secret in AWS Secrets Manager. The agent picks up the new token on its next container start.

Rotate the App-Level Token (xapp-)

1. Go to Basic Information → App-Level Tokens.
2. Click the token name to expand it, then click Revoke.
3. Click Generate Token and Scopes, re-add the connections:write scope, and click Generate.
4. Copy the new xapp-… token and update the argus/<tenant>/slack-app-token secret in AWS Secrets Manager.

Update the allowed-user list

The agent allowlist (ALLOWED_SLACK_USERS) lives in the same Secrets Manager secret as the tokens. To add or remove a user:

1. Open AWS Secrets Manager, find the secret named argus/<tenant>/credentials, and click Retrieve secret value → Edit.
2. Update the ALLOWED_SLACK_USERS field (comma-separated member IDs, e.g. U01ABC23DEF,U02XYZ45GHI).
3. Save the secret. The change takes effect on the next container start.