Connect Slack
This guide is for Owners and Admins, and for partners who set up Slack for a customer. At the end a Slack app in the customer's workspace answers with the Company Bots you chose.
The app belongs to the customer. It lives in the customer's Slack workspace. GEKI has no shared Slack app and no Slack Marketplace listing. A setup in the Console guides you. See Slack and Teams for how bots answer once the app runs.
Before you start
- You are an Owner or Admin of the organization. A partner switches into the customer's organization first. See Partners.
- You may create and install apps in the Slack workspace. Ask a workspace admin if you may not.
- At least one Company Bot is live. See Build your first Company Bot.
- The app takes its name and colour from Settings: the display name and the brand colour. Its description is "Company Bots of" and the display name. The publisher from Settings goes into the long description of the app. Set them first.
1. Start the setup
Open Connections and choose Add connection, then Connect Slack. You can also open /connections/new/slack in the Console directly.
The setup has two steps: Slack app and Install.
2. Slack app
With a token. GEKI creates the app in your workspace for you.
- Open api.slack.com/apps. Scroll to Your App Configuration Tokens, choose Generate Token, pick the workspace, and copy the Access Token. It starts with
xoxe. - Paste it into Configuration token and select Create Slack app.
GEKI uses the token once and does not store it. If the display name is longer than 35 characters, the setup also asks for a shorter app name.
By hand. Select Continue by hand. Create Slack app opens Slack with the manifest filled in. Pick the workspace and create the app. You can also download the manifest and paste it in Slack under Create New App, From a manifest. Then copy the Signing Secret from Basic Information and enter it in the Console.
A manifest cannot carry an icon. Upload the icon in Slack under Basic Information, Display Information. In channels, a reply uses the name and icon of the bot that answers. Direct messages keep the name and icon of the app.
3. Install
Select Add to Slack. Slack asks you to allow the permissions of the app and brings you back to the Console. GEKI tests the connection.
By hand: in Slack, open Install App and install the app to the workspace. Copy the Bot User OAuth Token from OAuth & Permissions. It starts with xoxb-. Enter it in the Console and select Test connection.
The connection is named after the workspace when the setup is done. You can rename it on the Connection tab.
4. Invite the app
Invite the app to each channel where bots should answer, for example with /invite @name. The app listens only in channels it is a member of. When a channel is private, a member of that channel invites it.
Then choose which bot answers where on the Slack channel page. Write to the app in a channel to check it.
What the app may do
The manifest turns on:
- Direct messages with the bot in the agent view of Slack.
- The bot listens to the messages of every channel it is in. It reads only the threads it takes part in.
- Files in both directions.
- Interactivity, for the buttons that let a person pick a bot.
It asks for these bot scopes:
| Scope | Used for |
|---|---|
app_mentions:read | Mentions of the app |
channels:history, groups:history, im:history | Messages in public channels, private channels, and direct messages |
channels:read, groups:read, im:read | The list of channels and direct messages |
chat:write, im:write | Replies and new direct messages |
chat:write.customize | The name and icon of the bot on a reply in a channel |
files:read, files:write | Files people send and files the bot creates |
users:read, users:read.email | Matching a Slack user to a member of the organization by email |
assistant:write | The agent view and its status line |
The signing secret lets GEKI check every request from Slack. GEKI rejects a request with a wrong signature or an old timestamp, and ignores an event from another workspace. Credentials are stored encrypted and never shown again.
The connection page
The page has two tabs.
- Connection. The status, the workspace, Test connection, Rename, which secrets are set, Run setup again, and Delete connection.
- Slack app. Download the manifest to update the app.
Update the app
Slack does not let GEKI change the app later. Update it by hand after a change of the display name, the brand colour, or the publisher in Settings, and when the Console shows that a newer manifest is available.
- On the Slack app tab, select Download manifest.
- In Slack, open the app, select App Manifest, paste the manifest, and save.
- If Slack asks, reinstall the app.
- Select I updated the app in the Console.
When something is wrong
| Reason | What to do |
|---|---|
| A credential is missing | Open the setup again with Run setup again. |
| Not tested | Select Test connection. |
Test failed, invalid_auth | The bot token is wrong or the app was uninstalled. Install the app again. |
| The app is missing permissions | Update the app with the current manifest, reinstall it, and test. |
| Slack: update the Slack app | Follow Update the app. |
If the bot does not answer in a channel, check that the app is a member of the channel, that the connection is Connected, and that the bot is live.
Remove the connection
Select Delete connection on the Connection tab. Bots stop answering in the workspace at once, and the channel settings are deleted. The Slack app stays in Slack. Remove it there.
Next
- Slack and Teams describes how bots answer and who may use them.
- Connect Microsoft is the same task for Microsoft.
- Set up your organization covers members, groups, and Chat.