Rich Slack Statuses

---

Allows you to automatically configure rich Slack statuses, including the emoji, text, and do not disturb and away settings.

🧐 About

For companies that use Slack for communication, your status is an extremely powerful tool to help let others know your availability and set expectations on how quickly you might reply. However, manually maintaining an accurate status in a busy working environment is practically impossible. While there are existing integrations for syncing your status to a calendar (eg, the Google Calendar app), these are quite limited as they do not let you customise your status.

With Rich Slack Statuses, you can customise all aspects of your Slack status using a standard Calendar:

• Status text
• Status emoji
• Do not disturb (aka snooze) setting
• Presence (away/online) setting

This works by finding all active events and parsing the title:

• The status emoji is set by specifying the emoji name in the event summary, surrounded by : (eg, :no_entry:). If no emoji is found, this defaults to calendar.
• Enter the [DND] flag to enable Do Not Disturb (snooze). This will also automatically set the emoji to :no_entry:, unless another emoji is explicitly provided.
• Enter the [AWAY] flag to set the presence to away, otherwise the presence is set to auto which uses your activity to mark you as online/away.
• The event summary is used to set the status text, with any parsed info (eg, emoji, flags) removed.

The active event is currently determined by finding all events that are currently occurring, and selecting the event which started last and then ends first. If you wish to override the selected event, prefix the summary with !.

🏁 Getting Started

Prerequisites

• Node.js 20
• Yarn 1
• GCP service account (required to read from a Google Calendar)
• Slack app

Installing

Clone the repository:

git clone git@github.com:bnjns/rich-slack-statuses.git

Install dependencies:

yarn install

Configuring

There are 2 types of properties that can be configured:

• Normal: Configured via environment variables; the value of the config property is the value of the environment variable.
• Secret: For sensitive values (eg, credentials). Instead of containing the value, the environment variable will contain the location of the secret (eg, for AWS Secrets Manager it would contain the ARN of the secret). See Secrets for more details.

Config Property	Type	Required	Default	Description
SECRET_TYPE	Normal	N	env	The system to use to resolve secrets. See Secrets.
CALENDAR_TYPE	Normal	N	google	The type of calendar to use to determine the status. See Calendars.
CALENDAR_ID	Normal	Y	N/A	The ID of the calendar to determine the status from.
SLACK_TOKEN	Secret	Y	N/A	The User OAuth Token of the Slack app installed on your workspace.
GOOGLE_CREDENTIALS	Secret	N	N/A	The JSON credentials of the GCP service account, if reading from Google. Alternatively, use the gcp-credentials.json file.
AWS_REGION	Normal	N	eu-west-1	If using an AWS system for storing secrets, use this to configure the region the client is configured in.

Running the tests

Simply run the tests using the yarn script:

yarn test

You can also watch for changes and automatically with:

yarn test:watch

View the current test coverage:

yarn test:coverage

Running manually

You can run the application manually using

yarn run:local <command> [...<options>]

with any of the following commands:

• clear-status: Clear your Slack status.
• execute: Run the entire app flow, from reading the calendar to updating Slack.
• get-events: Prints the currently active events. The calendar ID can be provided as a 2nd argument, or use the CALENDAR_ID environment variable.
• set-status: Set your Slack status, with an optional event title as a 2nd argument. For example,

  yarn run:local set-status ':calendar: [DND] An example event'

Building

To transpile the Typescript into CommonJS (will be written to ./dist):

yarn build

To build this into a zip which includes all dependencies:

yarn build:lambda

You can also build this into an executable (eg, if you wish to run locally on a cron job):

yarn build:package

This requires that you have pkg and a valid Node.js runtime installed.

🎈 Features

Slack app

At the moment, you will need to create your own Slack app within your workspace; simply head to https://api.slack.com/apps, and click Create New App. You can use the included manifest to simply the process.

Once created, you will need to install it to the workspace; go to Settings > Install App and press Install to Workspace. This may require administrator approval, depending on your workspace settings.

Once installed, you can configure the SLACK_TOKEN variable with your User OAuth Token.

Note: The User OAuth Token is specific to a user; each user wishing to use this application will need to install it themselves.

Calendars

This can currently read calendars from the following:

• google: Google Calendar

Select the desired calendar with the CALENDAR_TYPE environment variable (defaults to google).

Google Calendar

Ensure you have a GCP service account which has read access to the desired calendar, and set the JSON credentials in either the GOOGLE_CREDENTIALS secret or a gcp-credentials.json file.

• Settings and sharing > Share with specific people
• Add the service account email with the See all event details permission

The calendar can then be configured by setting the CALENDAR_ID environment variable.

Secrets

This app has different methods for retrieving secrets, such as the Slack token, depending on your desired config and deployment method; simply set the SECRET_TYPE environment variable to the desired method:

• env: Use environment variables. The secret value is the environment variable name. Not recommended in production.
• aws-ssm: Use AWS Systems Manager Parameter Store to store secrets. The environment variable should contain the parameter name.
• aws-secrets: Use AWS Secrets Manager to store secrets. The environment variable can contain either the name or ARN of the secret.

Predefined configurations

To make it easier to configure your status, this comes with a series of "predefined" configurations, which match on the event summary text (case-insensitive) to automatically set the emoji:

Text	Emoji
1:1	no_entry
A/L	palm_tree
Bank holiday	palm_tree
Focus time	no_entry
Interview	interview^
Jira	jira2^
Out of hours	zzz
Travelling	car

^ This is a custom emoji

Note: You can still override the emoji by specifying it in the event summary.

🚀 Deploying

Deploying in the cloud

This application is designed to be deployed in a cloud serverless environment (eg, AWS Lambda) as a CommonJS module, and can simply be run using a CRON schedule (eg, every minute). You can build this into a zip using the included script:

yarn build:lambda

You can then configure the handler based on the deployment platform chosen:

Platform	Handler
AWS Lambda	entrypoints/aws-lambda.default or entrypoints/aws-lambda.handler

Deploying locally

If you do not wish to deploy to a cloud service you can also run this locally, using something like crontab. Simply configure the cron job to run yarn run:local execute, or use yarn build:package to build an executable.

⛏️ Built Using

• Google Calendar API
• Slack Web API
• Luxon
• Winston
• pkg

✍️ Authors

• @bnjns