Thanks for checking out this Slack app Source Code! In a few minutes, you'll have a fully customizable, infinitely scalable Slack bot live in one of your Slack channels running on StdLib!
To get started, press the Install to Slack button below the editor to deploy the functions that will power your Slack app. After that, we'll walk you through some additional steps in your Slack dashboard.
If you would like to install this source from the command line, make sure you have Node.js installed on your machine. Then, install our command line tools by following the directions on this page. Once you've done that, create a StdLib workspace with
lib init (you will be prompted to create an account if you haven't already). From that workspace, run
lib create -s @slack/app to retrieve this source and generate a scaffold StdLib service directory for you Slack app.
cd into the directory you've just created.
You’ll be asked to enter a Service Name, we recommend
slack-app for this tutorial.
Next, you should create a Slack app. First, make sure you’re signed in to Slack. Next, visit your Slack Apps page at https://api.slack.com/apps. You’ll see a screen that looks like the following, though you may not have any existing apps yet.
At the next screen, simply click Create New App to create your app. You’ll be presented with a modal to enter in your App Name (I recommend “Test App” for the purposes of this tutorial) and the Development Slack Team you’d like to add it to.
From here, click Create App and you’ll find yourself on a Basic Information page.
You should now make sure your Slack App Credentials are properly assigned to your StdLib service. Switch back to your command line — you’ll want to open your
env.json (environment variables) file in the main service directory you've just created, open the file in your text editor of choice. We’ll be making modifications to the "dev" environment variables — make sure you’re modifying the right set!
First, fetch your StdLib Token from your StdLib Dashboard. You’ll be asked to log in again — once you’ve done so, click on Library Tokens on the left and you’ll see this page:
This is your StdLib auth token. Click Show token to see its value and copy and paste it to your env.json file under
STDLIB_TOKEN. Please note that dev values are for your dev environment and release values should only be populated when you’re ready to release your app.
Next, fill out
SLACK_APP_NAME. You should differentiate between your dev / release apps — make sure this is unique for every app you build, as it sets a unique identifier for data storage and retrieval. For the dev environment you can set this to "Test App".
Finally, go back to your Slack App, and scroll down on the Basic Information panel:
Copy each of these values to dev section of env.json:
As a last step, modify
https://<username>.lib.id/[email protected]/auth/ where
<username> is your StdLib username. You may also need to change the
slack-app section of the URL as well if you have named your service something other than
To make sure your Slack app is ready, we can test it locally. Let's try running a test “Slash” command — for example, this would respond to /hello hey there when run in your team in the channel “general” by the user “test”. From a terminal, set your working directory to your StdLib service directory if it isn't there already, and run:
$ lib .commands.hello test general "hey there"
You should see a response like this:
We can test events as well. For example, this as a “message” event that will be triggered any time a message is posted to a public channel (somebody writes “hey”):
$ lib .events.message test general "hey"
And you should see something like the following:
Now that we’ve set the appropriate environment variables in our StdLib Slack service, we’re ready to push our app live! Simply deploy with:
$ lib up dev
Before your app will be functional in your Slack channel, you'll have to register a few more webhooks in your Slack dashboard. We'll walk through these steps now.
Any interaction models that involve conversation, uploading files, etc. will rely on a bot, so let’s make sure we add one. Find the Bot Users option on the left sidebar, under the Features heading.
Click Add a Bot User to create your bot. You’ll be given an option to enter in the bot username — the default
@test_app should work just fine. Click Add Bot User to complete the process, and that’s it! Your bot user is now added and ready to be used.
Next, we’ll enable OAuth. On the sidebar menu, click OAuth & Permissions. Once there, you’ll want to enter in a Redirect URL as follows:
Hit Add and then click Save URLs. You should get a success message, and OAuth is ready!
Slash Commands are how Slack Apps respond to
/command style queries. You can read more about them on the Slack Slash Commands API Reference. We know from a previous step that our service has a pre-built response to
/hello, so let’s add that first. Click Slash Commands on the sidebar.
After clicking Create New Command, you’ll be asked to enter some command details. Make sure you enter the following:
Finally, we want to enable Event Subscriptions. Events are anything that can happen in your public channels, groups and messages. You can read more about the Slack Events API here.
To enable them, click on Event Subscriptions option on the left sidebar. Toggle events to On in the top right, and then put in your Request URL:
Slack sends a
challenge parameter to this endpoint, which is why we had to make sure we deployed our service earlier. This endpoint should get automatically verified, if not, make sure you go back and ensure that you deployed your service.
Finally, scroll down a bit to Subscribe to Team Events and add message.channels. Make sure to hit Save Changes in the bottom right corner!
https://<username>.lib.id/[email protected]/ in your web browser. You’ll see a very simple “Add to Slack” button.
Click this button, and accept the requested permissions (we set them up previously), you’ll have to scroll down and click Authorize.
You’ll be returned to your specified auth callback, which should give a success message!
Please note, your bot is now “production-ready,” by authorizing access above and setting up commands and events, your bot is all ready to go — though you can invite your bot to specific channels, it is not necessary for the basic interaction model.
Note: If you get an error with something like
OAuth Error: invalid_team_for_non_distributed_app, Slack thinks you are trying to install your app to the wrong workspace. To fix this, change the URL in your browser to the URL for the workspace you would like to add your app into.
You’re all done. Try it out! Your Slack App is now available for use in the Slack Team you authorized it for. By default, “Test App” should respond to a
/hello command and to the regex pattern
/hi|hello|sup|hey/ in normal channel messages.
You can modify these behaviors in your StdLib service directory at
functions/events/message/__main__.js. You can even create your own event responses and commands — just make sure for Slash Commands that you enable them via the Slack App management portal and your app has the correct permissions.
You can also Enable Distribution for this app and share it with other people by linking them to
https://<username>.lib.id/[email protected]/, but we recommend creating a separate Slack App for this purpose and using
lib release (so you don’t need the @dev qualifier). Full documentation for the StdLib command line tools is available on Github.