Enhancing Slack’s Events API

New Events API Adapters for Node.js and Python

Today we’re releasing two new tools for Node and Python that enhance and simplify our Events API.

We launched the Events API last summer as a more streamlined way to build Slack apps and bots. Compared to the older, firehose-like RTM API, the Events API is like a watering can: it allows you to build more scalable products by subscribing to just the events your app requires, all delivered neatly via HTTP. Startups like Polly said switching over to the Events API “allowed [them] to provide magical experiences without the hassle of keeping thousands of web socket connections alive.”

After talking to many of you and seeing how you’re using the Events API, we started seeing useful best practices, helpful patterns, and opportunities to abstract out common tasks emerge. It was clear there was demand for something that would make the Events API as easy to work with as the Slack Developer Kits do for the rest of the API. These tools do exactly that, and we’ll continue to update them as we find more ways to improve.

Besides being a more scalable option than the older RTM API, our Events API is especially helpful if you’re interested in building for Slack Enterprise Grid. We want to give you the tools and information you need to build a truly enterprise-ready Slack app. If you want to build a new product for Enterprise Grid, or if you want to update an existing app for shared channels, our Events API has many advantages; notably, it de-dupes events pertaining to shared channels into a single HTTP request.

Keep reading to learn how to build a Slack App using these adapters.

Let’s build

Let’s make a production-ready Slack App with a Bot User that incorporates OAuth to be installed within a team, listens for updates from the Events API, and sends data with the Web API. Whoa. Intimidated? Don’t be — it should only take a few minutes with our new adapters and their example code.

Before diving in, fetch the example code for either Node or Python. You can git clone the entire repository or just download it as a .zip and decompress to your chosen location.

Create a Slack App

Visit the Slack App creation page. Give your app a name and assign it to a development team. If you haven’t already, it’s a good idea to create a free team for your development work so you don’t interrupt real people getting work done.

Click “Create App” when you’re done.

Next, we add the Bot User configuration (this is because our example has a Bot User, but this step isn’t necessary for all Slack apps using the Events API; some apps prefer to listen for events without needing a named entity within the team). Use the left side navigation to select “Bot User”, click “Add a Bot User”, and then fill out a name and turn its presence on. This is important when using the Events API instead of RTM. RTM will show your bot as available when the RTM socket is connected, but for the Events API, this is the only way to make your bot appear available.

Next, select “Event Subscriptions” from the navigation on the left. Here, we’ll force the generation of a verification token. Enable events by toggling the associated switch, then input any HTTPS URL into the Request URL field. Don’t worry when it says verification failed; that’s all we need to do for now.

Now we’ll switch to the “Basic Information” page using the left side navigation, where we’ll see the three string values needed to set up our server:

• Client ID: A value that Slack uses to uniquely identifies your app from others.
• Client Secret: A value your app uses to prove to Slack that you are the owner of the Client ID. Keep this unpublished and secret.
• Verification Token: A value your app uses to verify that HTTP requests it receives are coming from Slack. Keep this unpublished and secret.

Configure and run the application

Before we can run the application, we need to choose a publicly-accessible URL that is secured with TLS (begins with https). What a pain! Thankfully, there are excellent development proxy tools that will help you accomplish this. For this tutorial we’ll use ngrok. The READMEs will give you guidance on how this can be done with localtunnel as well.

A development proxy is simply a tool that redirects traffic from a publicly accessible domain name to a local server which has no name on the internet. Both of these tools also handle securing connections with TLS and are free (with some limitations)! Note that they are strictly for development purposes and shouldn’t be used when your app starts being installed by real teams doing real work.

Start the development proxy and select a local port it can expect to redirect the traffic to (in this case 3000, the default in our example code). If you need a little guidance, take a look at our tunneling with ngrok tutorial.

Take note of the second forwarding address (it’s the one that begins with “https”); in our case https://de522ddf.ngrok.io.For the rest of this tutorial, we will call this our base address.

Now let’s configure the example application. For this we need to recall the Client ID, Client Secret, and Verification Token values, and export them into our shell’s environment variables. Type the following into your command line, but replace the <…> with your app’s values.

export SLACK_CLIENT_ID=<Client ID>
export SLACK_CLIENT_SECRET=<Client Secret>
export SLACK_VERIFICATION_TOKEN=<Verification Token>

Let’s run this puppy! Change to the example app directory in your shell. For Node, install dependencies with npm, and then run npm start (read more). For Python, create a virtualenv, activate it, install the dependencies with pip, and run python example.py (read more).

Almost there…

Now our app is running locally, and there’s a development proxy making it accessible on the web. Let’s connect the dots and tell Slack how to send the Events to the right place.

Head back to the app management page and select “Event Subscriptions” from the side navigation. Now we’re going to plug in a real Request URL and subscribe to some events. The Request URL combines our base address from earlier with the path where our example app listens for events (/slack/events). Using the example above, this would be https://de522ddf.ngrok.io/slack/events.

Pro tip: The Node adapter contains a command line tool, slack-verify. It can help you get a verified Request URL when you configure your app, before getting your server running, which is especially useful when starting a Slack app from scratch.

Toggle the switch to enable events once again, input your request URL, and you should get a message that the URL was verified successfully. Next, click the “Add Bot User Event” button to add two subscriptions: message.channels and reaction_added. Save your changes.

The last bit of configuration is for OAuth. Choose “OAuth & Permissions” from the side navigation. We’ll input a Redirect URL that combines our base address with the path where our example app listens for the OAuth redirect (/auth/slack/callback). Using the example above, this would be https://de522ddf.ngrok.io/auth/slack/callback. Once again, save your changes.

Using the App and Understanding the Code

We made it! Let’s give it a spin.

Open a browser to your base address. You should see a nice “Add to Slack” button. Click that button to see a permissions page for your development team (if you’re signed into more than one team, you’ll have to select it from the list.) You should be redirected back to the example app with a success message.

What just happened? Slack uses OAuth to request permission from a user to install the Slack app on his or her team. Once you (as a user) agree, you enable the individual services in the app configuration to work on the development team. The app’s bot user is added to the team, and the app receives a bot access token for interacting with the Web API. Also, you just gave Slack permission to send HTTP requests to the app’s registered Request URL when the actions the app cares about (message.channels and reaction_added) occur. Let’s trigger some of those actions and see how the application handles them.

First, invite our new bot into a channel on that team: log in to your Slack team from the web or from a desktop or mobile app. Then, invite the bot by sending /invite @greetandreact (or your bot’s name) as a message in a channel.

Send a message that includes “hi”. The two examples for each language handle this almost exactly the same way. The adapter dispatches an event, and the app listens for it and runs a handler (Node, Python). The handler gets every message in that channel, but it performs some work to search for “hi” in the text; if it matches, it will greet the user who sent that message.

Now react to a message in that channel with an emoji. Once again, the examples handle the reaction by running a handler (Node, Python). This time the handler sends a message with the same emoji. Hey bot, are you mocking me?

And that’s it! There’s a bit more code in each of the applications to handle OAuth and keep data structures up to date. Notice how your application didn’t have to figure out how to deal with HTTP requests, how to verify tokens, or even how to structure the event handling code. The adapters took care of this for you! As our platform evolves, delivering more ways to simplify your Slack apps, we’ll update these adapters so your app can use them, too.

Ready to start building an app or bot for Slack? There’s no better time to start than now, and no better place than here.

By Ankur Oberoi. Thanks to Jason Roche, Bear Douglas, and Taylor Singletary.