Slack has just released their new ‘Add to Slack’ button that’s designed to make it super easy to install add-ons into your Slack channels.
Slack invited us to their early-access beta and we’ve successfully integrated this into our 99designs Tasks product.
Interested in developing your own Slack integration? We’ll walk you through what to do.
Why use the ‘Add to Slack’ feature?
—
The strength of the ‘Add to Slack’ button is how simple it makes the installation of third party Slack addons. Installing these addons previously involved some awkward copy/pasting of API tokens and strange looking webhook URLs—not anymore!
The only downside is that the feature set is currently limited to posting messages to a single channel. We’re hoping this will expand to include some of the features we use in our more comprehensive Tasks Slack bot.
Getting started
—
The ‘Add to Slack’ button uses Slack’s OAuth2 API. OAuth2 is a protocol that lets your application request access to a user’s Slack account without needing their password.
Let’s run through the basic flow.
Step 1: Register your application
The first thing you will need to do is register your application with Slack.
Don’t worry if you don’t have all the details just yet, you can fill in the blanks later.
Once you’ve registered your application, you’ll get a Client ID and Client Secret for your application. You’ll need these a little bit later.
Step 2: Place the ‘Add to Slack’ button on your website
Slack provides a code snippet in their Slack button documentation that can be copy pasted into your website.
If you look closer at this snippet, the important part is that your application should link to https://slack.com/oauth/authorize with the following parameters:
client_id Client ID of your registered Slack application.
scope Must be incoming-webhook
state Unique string that’s passed back upon completion (optional, but recommended)
Pro tip: Slack recommends using the state parameter to avoid forgery attacks. We use the HMAC encryption algorithm using a combination of the 99designs user ID and a secret value to generate a digital signature. This signature lets us verify the user is the same when they’re redirected back to our website later.
Step 3: User clicks button and authorizes access to Slack
Now that the button is on your website, users can click the button and will be asked to authorize access to their Slack account. They’ll also be able to choose a channel for messages to be posted to.
Step 4: Slack redirects back to your application
Once the user has clicked Authorize, they will be redirected back to your application’s configured redirect URL with an extra code query string parameter.
This code parameter is a single use code that can be used to request a more permanent Slack API token and webhook URL.
Note: If you passed a state parameter earlier, it is passed back at this point too. Use it to verify the user is still the same one that clicked the button in the first place.
Request the Slack API token and webhook URL by making a http POST request in your server code to https://slack.com/api/oauth.access with these parameters:
client_id Client ID of your registered Slack application.
client_secret Client Secret of your registered Slack application.
code The code returned by Slack in the query string parameter.
Refer to the Slack oauth.access API docs for more details.
This request will return a JSON response with a more permanent Slack API token and a webhook URL for posting notifications into the channel of the user’s choice.
You’ll need to store these details in your database for later use.
We’d also recommend requesting a few more details about the Slack user using the Slack auth.test API. Knowing the user’s Slack username can help your application properly @mention the user in Slack messages.
Step 5: Call webhook when something happens
At this point, you have a webhook URL saved in your database that can be used to post messages to Slack. Aim to keep your messages useful, relevant and as informative as possible—try not to overwhelm them with too much!
We started by replicating our email notifications as messages through Slack.
To send a message via webhook, make a http POST request to the webhook URL with a JSON string as the request body. A simple message might look like this:
{ "text": "Something happened: <https://99designs.com/tasks/|Click here> for details." }
Check out the Slack API docs for more details on what’s possible with webhook messages.
Step 6: Adding some style
Slack provides a variety of formatting options for changing the appearance of text, adding links as well as options for richly formatted messages with file attachments, image previews and border colors.
Thank you Slack!
—
We wanted to say a big thank you to the Slack team for their fantastic work on the ‘Add to Slack’ button. It was great to be part of their beta program and we can’t wait to see what’s coming next.
