Connecting Slack

Before you start#

• A Slack workspace that lets you add apps. Many need an admin to approve a new app, so ask first.
• About 15 minutes, all on one Slack settings site.
• Somewhere safe for the two tokens. Anyone who has them can message as your app.

1. On the computer Archie is on, open the Slack apps page in a browser and click Create New App:

   https://api.slack.com/appsCopy

   It hands you two long tokens for Archie, so setting it up on a phone means mailing both to yourself.

2. Choose Blank app, then click Continue.

3. Give the app your agent’s name, pick its workspace (or create one), then click Create.

   My AgentCopy

4. Open Settings → Socket Mode and turn it on. It asks you to name a token, then makes an xapp- token: copy that into the App-level token box on Archie’s Chat app card (the top one). Any name works, like this:

   My Agent socketCopy

5. Open Features → App Home, scroll to Show Tabs, turn ON the Messages Tab, and check “Allow users to send Slash commands and messages from the messages tab”. Without this, Slack won’t let you message the bot.

6. Open Features → Interactivity & Shortcuts and turn it on (no URL needed). This lets you tap your agent’s buttons instead of typing.

7. Open Features → Event Subscriptions and enable it. Expand “Subscribe to bot events”, click Add Bot User Event, add message.channels, message.groups, message.im, and message.mpim (leave one out and it can’t hear you there), then click Save Changes (bottom right).

8. Open Features → OAuth & Permissions, scroll to Scopes → Bot Token Scopes, click Add an OAuth Scope, and add each of these: chat:write, channels:history, groups:history, im:history, mpim:history, files:read, files:write, users:read.

   The four history scopes are the places it can be spoken to: public channels, private channels, direct messages, and group messages. files:write lets a file it makes arrive in Slack; users:read lets it call you by name.

9. Scroll back to the top of that page, click Install to Workspace, then Allow. Copy the Bot User OAuth Token (it starts with xoxb-) into the Bot token box on Archie’s Chat app card.

10. Message your agent: open a direct message to it, or type /invite @your-bot in a channel and message it there. (It only replies while Archie is running on your computer.)

You’ll know it worked when#

The Slack row on Archie’s Chat app card says connected in green, and your app appears in Slack under Apps. Your agent won’t answer until you claim it: send it a direct message and it asks for a six-digit code. The Claim your agent guide covers this.

If something goes wrong#

• The message box is missing or grayed out: in Features → App Home, turn ON the Messages Tab and check “Allow users to send Slash commands and messages from the messages tab”. Slack needs both.
• Archie rejects a token: the xapp- token goes in the App-level box, the xoxb- one in the Bot token box. The xoxp- token is your personal one; it saves but never replies.
• You show as Unnamed, or replies stopped after a settings change: a scope counts only after you reinstall the app, which issues a new bot token. Paste both tokens into Archie again.
• Nothing replies: Archie has to be open on your computer and the agent started. In a channel, the app also has to be invited with /invite.