# 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](/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](/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](/guides/first-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.

1. Open [api.slack.com/apps](https://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`.
2. 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](/slack-and-teams#choose-which-bot-answers-where). 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.

1. On the **Slack app** tab, select **Download manifest**.
2. In Slack, open the app, select **App Manifest**, paste the manifest, and save.
3. If Slack asks, reinstall the app.
4. 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](#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](/slack-and-teams) describes how bots answer and who may use them.
- [Connect Microsoft](/guides/connect-microsoft) is the same task for Microsoft.
- [Set up your organization](/guides/set-up-organization) covers members, groups, and Chat.