# Setting up the Slack app

Source: https://codeherder.com/docs/slack-app/

Create your own Slack app from the shipped manifest, set three environment variables, then connect Slack.

CodeHerder posts task events to Slack channels. The **Slack app** makes this possible. A self-hosted server runs its own Slack app. This page covers the app setup. [Posting task events to Slack](https://codeherder.com/docs/slack/) covers everything after it.

## Why you run your own app

Slack fixes the OAuth redirect URL of an app to one domain. The hosted CodeHerder app redirects to the hosted server. A self-hosted server has a different domain, so it cannot use that app. The signing secret also belongs to one app. Your bot token and your events stay on your own server.

## Create the app

1. Open the Slack app page and choose **Create New App**.
2. Choose **From a manifest**, then pick the Slack workspace that owns the app.
3. Paste this manifest. It already holds the URLs of your server.

```
display_information:
  name: CodeHerder
  description: Posts CodeHerder task events to Slack channels.
features:
  app_home:
    home_tab_enabled: false
    messages_tab_enabled: true
    messages_tab_read_only_enabled: false
  bot_user:
    display_name: CodeHerder
    always_online: false
oauth_config:
  redirect_urls:
    - https://api.codeherder.com/v1/oauth-callback
    - https://api.codeherder.com/v1/slack/link/callback
  scopes:
    bot:
      - chat:write
      - channels:read
      - groups:read
      - im:write
      - channels:history
      - groups:history
      - im:history
      - commands
      - app_mentions:read
      - files:write
      - reactions:write
      - links:read
      - links:write
      - users:read
    user:
      - openid
settings:
  interactivity:
    is_enabled: true
    request_url: https://api.codeherder.com/v1/slack/interactions
  event_subscriptions:
    request_url: https://api.codeherder.com/v1/slack/events
    bot_events:
      - app_uninstalled
      - tokens_revoked
      - message.channels
      - message.groups
      - message.im
      - app_mention
  org_deploy_enabled: false
  socket_mode_enabled: false
  token_rotation_enabled: false
```

The manifest asks for the history scopes and the message events. They let CodeHerder read replies in task threads. It also sets the Interactivity URL, which the Approve, Reject, Answer and Unblock buttons need.

Slack checks the events URL when you save. The check fails until the server knows the signing secret. If it fails, finish the next two sections first. Then open **Event Subscriptions** and retry the URL.

## Update an existing app

An app made before threads and replies lacks some scopes and events. Delivery keeps working without them. Threads and replies stay off until you add them.

The new bot scopes are `im:write`, `channels:history`, `groups:history` and `im:history`. The new bot events are `message.channels`, `message.groups` and `message.im`.

The manifest also asks for scopes that no feature needs yet: `commands`, `app_mentions:read`, `files:write`, `reactions:write`, `links:read`, `links:write` and `users:read`. It subscribes to `app_mention` and turns on the App Home messages tab, so people can write to the bot in a direct message. They are there now so a later feature does not need another reinstall. After you save the manifest, reinstall through CodeHerder’s Slack page (**Connect** or **Reinstall**), not Slack’s reinstall banner. CodeHerder then stores the new token and scopes.

1. Open your app in Slack and choose **App Manifest**.
2. Paste the manifest from [Create the app](https://codeherder.com/docs/slack-app/#create-the-app), or add the scopes and events by hand. Save it.
3. Open the Slack page in CodeHerder and press **Reinstall Slack**. Approve the new scopes in Slack.

The prompt on the Slack page goes away once the installation holds every new scope.

## Turn on distribution

Skip this step when one Slack workspace installs the app. When several Slack workspaces install it, open **Manage Distribution** and choose **Activate Public Distribution**.

## Set the credentials

Open **Basic Information** and copy three values. Set them in the server environment.

| Slack value | Variable |
| --- | --- |
| Client ID | `CH_SLACK_CLIENT_ID` |
| Client Secret | `CH_SLACK_CLIENT_SECRET` |
| Signing Secret | `CH_SLACK_SIGNING_SECRET` |

All three are required. Restart the server after you set them. When one is missing, the **Connect** button on the Slack page is disabled. The page gives the reason and links to this page.

## Connect Slack and add routes

Once the server has the three values, connect Slack, invite the bot and add routes as described in [Posting task events to Slack](https://codeherder.com/docs/slack/).

## Add thread replies to an existing app

An app made from an older manifest lacks the history scopes and message events. Its connection posts one message per event, with no task thread. To update it:

1. Open the app in Slack. Under **OAuth and Permissions**, add the scopes from the manifest above. Under **Event Subscriptions**, add the message events.
2. In CodeHerder, open the Slack page. Click **Edit connection**, click **Disconnect**, then connect again. Approve the new permissions in Slack.

Your routes stay as they were. See [Turn on threads and replies](https://codeherder.com/docs/slack/#turn-on-threads-and-replies).

## Buttons

The Approve, Reject, Answer and Unblock buttons are on by default. They need the Interactivity URL from the manifest and the signing secret. To turn them off, set `CH_SLACK_INTERACTIVITY` to `false` and restart the server. Messages then post with no buttons. Each member also links a Slack account before a button acts for them. See [Act from Slack](https://codeherder.com/docs/slack/#act-from-slack).

## Troubleshooting

- **A route is off, or the connection is off.** See [Posting task events to Slack](https://codeherder.com/docs/slack/).
- **Connect answers `oauth_app_not_configured`.** One of the three variables is empty. Set it and restart.
- **Messages have no Approve, Reject or Answer buttons.** Check that `CH_SLACK_INTERACTIVITY` is not `false`. Check that the Interactivity URL in the Slack app matches the manifest.
- **Slack events fail with `invalid_signature`.** The signing secret is wrong, or the server clock is more than five minutes off.

## Related guides

- [Posting task events to Slack](https://codeherder.com/docs/slack/)
- [Integrations](https://codeherder.com/docs/integrations/)
- [Connecting the GitHub App](https://codeherder.com/docs/github-app/)
