Docs / Integrations / Slack

Connect Slack

Connect your Stand to your Slack workspace so it can DM you, reply to @-mentions in channels, and exchange files. Plan on about 15 minutes — Slack's app config has more toggles than Discord's, but every step is in here.

✦ Tip: Slack's app configuration page has six different toggles that all need to be set correctly. The fastest way through it is to ask Sutando to guide you hands-free. In AG2 Space, start a voice session with your agent, share your screen, and say "help me set up Slack" — it will read the api.slack.com config page with you and narrate each click.

Before you start

A Slack workspace you're a member of. Personal workspaces work — Slack is free for small teams (or solo).
Permission to install an app in that workspace. Workspaces with strict admin policies may require an admin to approve.
AG2 Space installed and signed in. If not, grab it from desktop.ag2.space.

⚡ Fast path — create from a manifest

Rather than setting scopes, events and the messages tab by hand, let a manifest do it in one shot. At api.slack.com/apps click Create New App → From a manifest, pick your workspace, paste the YAML below, and click Create. It pre-sets Socket Mode, every bot scope, the DM + @-mention events, and the messages tab.

app manifest · YAML

display_information:
  name: Sutando
features:
  bot_user:
    display_name: Sutando
    always_online: true
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
oauth_config:
  scopes:
    bot:
      - app_mentions:read
      - channels:history
      - chat:write
      - files:read
      - files:write
      - groups:history
      - im:history
      - im:write
      - users:read
settings:
  event_subscriptions:
    bot_events:
      - app_mention
      - message.im
  socket_mode_enabled: true

The manifest can't mint tokens, so finish with two manual bits: generate an App-Level Token with connections:write (Step 2 below — the manifest turns Socket Mode on but can't create the token), click Install to Workspace, then copy the xoxb- and xapp- tokens into AG2 Space → Settings → Channels → Slack. You can skip the scopes, events, and messages-tab steps.

Create the Slack app

Open api.slack.com/apps and click Create New App → From scratch.

Name it something memorable — your name plus a hyphen plus something like sutando works (e.g. ada-sutando). Pick the workspace you want the bot to join. Click Create App.

Enable Socket Mode + generate the App-Level Token

In the left sidebar, click Socket Mode and toggle Enable Socket Mode to On. Slack will prompt you to generate an App-Level Token. Name it anything, and add the scope connections:write.

Pick the right scope. The scope picker shows app_configurations:write near the top — that's NOT the one you want. Socket Mode specifically needs connections:write. If you pick the wrong one, Sutando will refuse to start with a missing scope error and you'll have to regenerate.

Generate the token. You'll see a long string starting with xapp-. Copy it — this is your App-Level Token.

Add bot scopes

Left sidebar → OAuth & Permissions. Scroll down to Bot Token Scopes (not User Token Scopes — leave that section empty). Click Add an OAuth Scope and add each of these:

bot token scopes

chat:write
im:history
im:write
app_mentions:read
channels:history
groups:history
files:read
files:write
users:read

The two that matter most for DMs are im:history (receive DMs) and chat:write (send replies). The files:* scopes let your agent exchange images and documents with you.

Enable Event Subscriptions

Left sidebar → Event Subscriptions. Toggle Enable Events to On.

Leave the Request URL field blank. With Socket Mode enabled, Slack delivers events over the WebSocket; you don't need a public webhook.

Scroll to Subscribe to bot events, click Add Bot User Event, and add message.im and app_mention. Click Save Changes at the bottom right.

If Save Changes is greyed out: the page was loaded before you turned on Socket Mode and doesn't know the URL field is optional. Hard-refresh the page (⌘⇧R) and try again. If it's still greyed, type any placeholder into the Request URL field (e.g. https://example.com/x) — Socket Mode overrides it after save.

Enable the Messages tab

New Slack apps have DMs disabled by default. Left sidebar → App Home. Scroll to Show Tabs → Messages Tab, and check Allow users to send Slash commands and messages from the messages tab.

Without this, the bot's DM screen shows "Sending messages to this app has been turned off" and your DMs never even leave Slack.

Install the app to your workspace

Left sidebar → Install App (or OAuth & Permissions → Install to Workspace at the top of the page). Click Install to Workspace and approve the permissions prompt.

After install, Slack shows your Bot User OAuth Token starting with xoxb-. Copy it.

Keep both tokens private. The xoxb- and xapp- tokens together give full access to your bot. Don't paste them into screenshots, chats, or commits.

Paste both tokens into AG2 Space

Open AG2 Space → Settings → Channels. Paste:

Slack Bot Token ← the xoxb- token from step 6.
Slack App-Level Token ← the xapp- token from step 2.

Both are stored locally on your Mac (never logged, never sent to the cloud). Scroll to the bottom of the Settings window and click Save. The setting only persists after you save — without this, the app keeps using whatever was in the fields before, and the bot stays offline.

Verify with your first DM

Open Slack. Find your bot — either click the workspace name in the top-left, search with ⌘K and type the bot's name, or look under Direct Messages in the left sidebar.

DM the bot — say "hello". Within a few seconds, your agent should reply. The first DM auto-enrolls you as the bot's owner — anyone else who DMs the bot afterwards is silently rejected unless you add them to the allowlist.

Troubleshooting

The bot never replies, even after I sent a DM

Check two things in order:

Event Subscriptions is on. Go back to the app config page → Event Subscriptions. The Enable Events toggle at the top must be green. If it's off, the bot is connected but Slack never sends it your messages.
Reinstall after scope changes. Any time you add a bot scope, Slack shows a yellow banner at the top of the OAuth page saying "Workspace needs to reinstall app". New scopes don't take effect until you click that reinstall button. Easy to miss.

"Sending messages to this app has been turned off"

You skipped step 5. Go to the app config → App Home → Show Tabs → Messages Tab → check Allow users to send Slash commands and messages from the messages tab. The DM input box should re-appear immediately.

"missing_scope" error in Sutando logs

The App-Level Token was generated with the wrong scope. Go back to Basic Information → App-Level Tokens, delete the existing token, and generate a new one — this time make sure the scope is connections:write (not app_configurations:write). Paste the new xapp- token into Sutando settings, save, and the bot should come online.

Bot replies in DM but not in channel @-mentions

Two checks. (1) You added app_mention under Subscribe to bot events (step 4). (2) The bot is a member of the channel — for public channels, mention it once in a thread to invite it; for private channels, use the /invite command from inside the channel. Bots can't auto-join private channels.

A teammate DMs the bot and gets no reply

By design. The first DM auto-enrolls one owner, and subsequent senders are silently dropped at the access gate. Open AG2 Space → Settings → Channels → Slack → add their Slack user ID to Allowed senders to let them through. (To find a Slack user ID: click their name in Slack, View profile, three-dot menu, Copy member ID.)

Stuck? Ask in the Sutando Discord

Join the Sutando community Discord to ask questions, share what you've built, or get unstuck.

What's next

Connect Discord →Connect Telegram →Back to docs →