Howdy! 👋 Welcome to the Word Cloud App for Slack, built using Bolt JS and also referencing the project structure from the Bolt JS Starter Template.
This Slack app will allow users to run a /word-cloud
command or "Word Cloud" shortcut in any Slack channel with the bot installed to generate a word cloud reflecting the most commonly used words for a specified date range.
Table of Contents
- 📁 functions
- 📃 word-cloud-functions.js: File that contains main functionality for pulling messages from a specified channel, generating a string to input to the Word Cloud API of all text within a date range, and then creating the word cloud using the API and uploading it to the specified channel.
- 📁 listeners
- 📁 commands
- 📃 index.js: Sets up event listener for commands - specificially, listening for the
/word-cloud
command configured for this app. - 📃 word-cloud.js: Initializes a callback and related functionality that is triggered when the
/word-cloud
command is called.
- 📃 index.js: Sets up event listener for commands - specificially, listening for the
- 📁 shortcuts
- 📃 index.js: Sets up event listener for shortcuts - specificially, listening for the Word Cloud shortcut configured for this app.
- 📃 word-cloud.js: Initializes a callback and related functionality that is triggered when the
/word-cloud
command is called.
- 📁 views
- 📃 index.js: Sets up event listener for views - specificially, listening for the Word Cloud shortcut modal configured for this app to be submitted.
- 📃 word-cloud-view.js: Initializes a callback and related functionality that is triggered when the Word Cloud shortcut modal is submitted.
- 📃 index.js: Initializes event listeners (ex: commands, shortcuts, views) for Slack. This is then called in
app.js
as part of app setup.
- 📁 commands
- 📃 .env.sample: Example template with required environment variables for a
.env
file to authenticate the app and any related API requests to Slack. - 📃 app.js: Primary app entry point that initializes the authenticated app and sets up the event listeners for the app.
- Make sure you have
npm
installed. To verify this, runnpm -v
in your Terminal. - Create an account on api.slack.com.
- Follow the first two steps of Bolt JS Getting Started Guide to set up an application under your Slack Developer account and generate access tokens.
- Create a
/word-count
slash command by following step #1: Creating a Slash Command here.
First-Time Setup
- Clone this repository. This will create a local directory called
word-cloud-app
. cd
into yourword-cloud-app
directory.- Create a
.env
file in your root directory based off of your.env.example
file and add yourSLACK_SIGNING_SECRET
,SLACK_BOT_TOKEN
, andSLACK_APP_TOKEN
values - this will be on your App's settings page on api.slack.com under Basic Information > scroll to the App Credentials category. - Run
npm install
in theword-cloud-app
directory to install all dependencies.
General Instructions
Once the above setup has been completed (or if you've run the app before), you can run the application using the following command in the project's root directory:
node app.js
To install the bot in Slack, first install it to your workspace. Then, add it into the desired channel you'd like to run the bot in. Once the bot is installed in the channel, you can call the /word-cloud
command or run the "Word Cloud" shortcut.
For both the shortcut and command flows - no date range is specified, then the bot will automatically query for messages from the last 30 days to the current date.
Shortcut Specific Notes
For shortcut modal input, please enter dates as YYYY-MM-DD
.
If only a "newest" date is specified in the shortcut prompt, then the bot will automatically query from messages from the last 30 days to the "newest" date that was specified.
Command Specific Notes
To specify a date range for commands, run /word-cloud [from YYYY-MM-DD] [to YYYY-MM-DD]
.
If only one date is specified for the command, the bot will automatically query for messages from that date to the current date.
Example Commands:
- To get a word cloud for January 1, 2022 to January 4, 2022, you would run
/word-cloud 2022-01-01 2022-01-04
. - To get a word cloud for January 1, 2022 to now, you would run
/word-cloud 2022-01-01
. - To get a word cloud for the last 30 days to now, you would run
/word-cloud
.
Command Example:
Shortcut Example: