Home Set up Slack app

Create the Slack app

Ten minutes, and the only part that touches Slack's settings. The manifest does most of it; the rest is three values and an invite.

1. Create the app from the manifest

Go to api.slack.com/apps, choose Create New App, then From an app manifest, pick your workspace, and paste the contents of slack-manifest.yaml from the repository.

The manifest sets the scopes, the slash commands, the event subscriptions and the App Home tab in one go, which is why it is worth using rather than clicking through the settings.

2. Add your redirect URL

Under OAuth & Permissions, add:

https://your-domain/oauth/callback

This has to match the APP_URL you configured, including https.

3. Copy three values

From Basic Information, copy the client id, client secret and signing secret into your environment or Helm values. The signing secret is what lets the app verify a request genuinely came from Slack; without it every event is rejected.

4. What it asks for, and why

Scopes are the part people read carefully, so here is each group and what it is for.

  • app_mentions:read: so the bot can answer when somebody @-mentions it in a channel.
  • team:read: the workspace name, shown in the dashboard and the digest.
  • channels:read, groups:read: to see who is in the channel a standup or a coffee chat draws from.
  • chat:write: to post the summary and the introductions.
  • im:write, im:history: to ask each person their questions in a DM and read their answers to it.
  • im:read: to list the app's own direct message conversations.
  • users:read: names and timezones, so nobody is asked at midnight.
  • users:read.email: the address a digest email is sent to.
  • users.profile:read: working hours, for suggesting a coffee chat time both people can make.
  • mpim:write, mpim:history: the group DM a coffee chat introduction happens in, and following it so a pair who are already talking is not nudged. Only coffee chats use them.
  • emoji:read: so kudos can use a custom token from your workspace.
  • reactions:write: the 🎉 under each celebration post. A workspace that has not granted it still gets the posts, without the reaction.
  • commands: the slash commands.

There is no scope for reading channel history, because the app never does.

If you installed before coffee chats existed, your workspace will not have granted the three mpim scopes. Coffee chats stay dark until you reinstall, rather than failing at runtime, and the dashboard tells you which scopes are missing.

5. Install and invite

Open your app URL, authorise, and you are the first admin. Then invite the bot to the channel the summary posts in, and to any channel you want coffee chats to pair from. The bot has to be in the channel before a standup can post there:

/invite @Morgenruf

Slash commands you get

  • /standup (or /morgenruf-standup): start your standup now
  • /skip (or /morgenruf-skip): skip today
  • /kudos @teammate a reason (or /morgenruf-kudos): give recognition
  • /morgenruf: what the bot can do
  • /morgenruf profile: your member profile, the birthday and start date celebrations read
Questions

About the Slack app

Why does it ask for so many scopes?

Each one has a single job, listed on this page. Standups need the basics: reading channel membership, writing messages, and opening DMs. Coffee chats add three more, because a group introduction is a multi-person DM. Kudos needs emoji read access to use your own token. All of them are requested at install, so a feature switched on later works without reinstalling.

What are the three extra coffee chat scopes?

mpim:write and mpim:history, to open and follow the group DM an introduction lives in, and users.profile:read, to read each person's working hours so a suggested time suits both.

Can I restrict it to one channel?

Yes. The bot only acts in channels it has been invited to, and each standup names its own channel. Nothing happens anywhere it has not been asked.

Does it read our messages?

No. It reads replies to its own DMs and the membership of channels you point it at. It has no scope to read channel history.

Who becomes the admin?

Whoever installs the app. That person can promote others, hand out per-feature grants, and always counts as an admin even if their member row is removed, so a workspace cannot lock itself out.

Free for every seat, and that is the whole pricing page

Add to Slack puts Morgenruf on the free hosted instance CloudDrove runs, in about two minutes. Or self-host the same MIT code with Docker Compose or Helm and pay only for the server.