Chapter 6. Webhooks and Slash Commands

Every bot we've created so far shares the same two traits: they rely on commands issued by users and require a Slack API token. This has been very useful in our bots so far, but what if we want a bot to post messages to a Slack channel without needing an API token? Plus what if we want a bot that does not require an API token to interact with users? An example of this is the GitHub Slack integration, a service that posts GitHub activity on specific repositories to a Slack channel of your choice.

In this chapter, we will discuss how to use webhooks to get data in and out of Slack and how to create slash commands that users can interact with throughout Slack.

We will cover the following topics:

• Webhooks

• Incoming webhooks

• Outgoing webhooks

• Slash commands

• In-channel and ephemeral responses

Webhooks

A webhook is a way of altering or augmenting a web application through HTTP methods. Previously, we used third-party APIs in our bots to get data into and out of Slack. However, this isn't the only way. Webhooks allow us to post message to and from Slack using regular HTTP requests with a JSON payload. What makes a webhook a bot is its ability to post messages to Slack as if they are a bot user.

These webhooks can be divided into incoming and outgoing webhooks, each with their own purposes and uses.

Incoming webhooks

An example of an incoming webhook would be a service that relays information from an external source to a Slack channel without being explicitly requested. An example of this is the aforementioned GitHub Slack integration:

The GitHub integration posts messages about repositories we are interested in

In the preceding screenshot, we can see how a message was sent to Slack after a new branch was made on a repository this team is watching. This data wasn't explicitly requested...

Slash commands

Commands that begin with a slash (/) are commands that can be used from anywhere within the Slack client. You are probably already familiar with the more common ones implemented by Slack themselves. For instance, use the topic command:

/topic Sloths are great

This will set the channel's topic to "Sloths are great." Like with incoming and outgoing webhooks, Slack allows teams to configure their own custom slash commands. To demonstrate their use, we'll build a bot that uses the popular computational knowledge engine Wolfram Alpha (http://www.wolframalpha.com/). The end goal is a bot that returns the results from the query submitted via the slash command.

Unlike webhooks, slash commands can only send data included with the command, so you are guaranteed to only receive data that was intentionally sent. Because of this nuance, we get an additional benefit to using slash commands. They are available to be used from any channel, DM, or private group.

First, let's set up the slash command...

In-channel and ephemeral responses

You might have noticed that when the Wolfram Alpha bot responds, it has the text Only you can see this message next to its name. As the text implies, the result of our bot is only visible to the user who initiated the slash command. This is an example of an ephemeral response. Note that the original slash command's text is also only viewable to the user that executed it. The opposite of ephemeral is an in-channel response, which can show both the slash command and result in the channel, for all to see.

By default, all slash command responses are set to ephemeral mode by the Slack API. Let's look at changing that and send in-channel messages instead. Once again, let's replace the contents of http.createServer. Go over the changes step by step:

// create a simple server with node's built in http module
http.createServer((req, res) => {
    res.writeHead(200, {'Content-Type': 'application/json'});

The main difference here is that we've changed the response...

Using webhooks and slash commands

Now that we have a firm grasp on what webhooks and slash commands are, we should establish when to use them. First, we should consider when we'd use a webhook or slash command over a bot user, which we've learnt to build in previous chapters.

A bot user generally operates on a one-to-one basis; every bot requires a Slack token unique to that bot, meaning that the bot can only interact with the team associated with that token. This also allows the bot to maintain a real-time messaging connection with Slack and to reconnect in case of connection failure. Webhooks and slash commands, on the other hand, exist as external services and can be reused by many teams. By removing the need for a Slack token, you open up your app to be used by many other teams.

Use this flowchart to decide whether a webhook or a slash command is best for your needs:

When to use webhooks or slash commands

In the preceding diagram, we mention the concepts of active and reactive. We covered...

Summary

In this chapter, we saw what webhooks are and how to set them up to send data out of Slack and get data into Slack through a third-party server. We also discussed slash commands and how to implement them.

In the next chapter, we will cover how to publish your app so that other teams can make use of your bots, webhooks, and slash commands.