Allows you to automatically configure rich Slack statuses, including the emoji, text, and do not disturb and away settings.
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 tocalendar
. - 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 toaway
, otherwise the presence is set toauto
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 !
.
- Node.js 20
- Yarn 1
- GCP service account (required to read from a Google Calendar)
- Slack app
Clone the repository:
git clone git@github.com:bnjns/rich-slack-statuses.git
Install dependencies:
yarn install
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. |
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
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 theCALENDAR_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'
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.
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.
This can currently read calendars from the following:
google
: Google Calendar
Select the desired calendar with the CALENDAR_TYPE
environment variable (defaults to google
).
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.
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.
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.
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 |
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.