How to Connect Displayr to the Slack API
Is your team on Slack? Did you know that you can connect Slack to external platforms to receive notifications? This post will show you how to hook up a Displayr document with the Slack API and generate custom alerts for your team. These alerts can tell you important things about the data you have set up in Displayr - like if a respondent has given you a worrisome NPS score or, on a positive note, when new people sign up to your blog or website.
In my Displayr document, I have an R table connected to a database that automatically refreshes every hour. This database provides details about people who have signed up to my new software package. Instead of manually checking to see how many people have signed up, I want to be automatically alerted of the number of sign-ups.
This is possible by connecting Displayr to Slack's API. Slack is a workplace tool which is used for communication and allows users to create "channels" for specific topics. These channels can in turn be used for receiving alerts via the API.
There are three key things that you need to get Displayr talking to Slack:
- A Slack channel where messages will be posted
- A Slack "app" that mediates the communication between Displayr and the channel
- R code running in your Displayr document which knows the details of the "app" and what messages should be sent
I cover all of these below.
Setting up your Slack channel
If you don’t already have a specific channel created for this task, it is easy to add one to your workspace. Once you have logged into your Slack app, simply click the plus icon (+) next to Channels on your left pane and the following window will pop up:
Give your new channel an appropriate name and decide whether you want it to be private or public (i.e., anyone within your workspace can view it). Press Create Channel and the channel will be added to your workspace. In this example I have created a channel called "api_test".
Setting up your app
Create a new app
In order to connect your Slack channel to Displayr, you will need to build a Slack app which will generate your OAuth and webhook parameters. Simply go to https://api.slack.com/apps and click the Create New App button at the top to give you the below screen.
Choose an appropriate name for your app and select your workspace from the drop-down provided, then press Create App.
You will now be presented with the Add features and functionality tab. Go to Permissions to start setting up the connection.
The next tasks are to set up the scope of this app and install it in your workspace. You can do this by following the below steps:
- Scroll down to Scopes and select Send messages as [Channel name] and Post to specific channels in Slack in the Select Permission Scopes drop-down, then press Save Changes.
- Now scroll up to the top again and press Install App to Workspace.
- Choose your desired channel in the Post to field and press Authorize.
This will generate your OAuth Access Token which you should copy. This in turn will automatically create your webhook link which you will also need to copy. You can find this by clicking Incoming Webhooks on the left pane and it will display your webhook URL under Webhook URLs for Your Workspace.
Use an existing app
If you already have built an app in Slack and wish to use that instead, you can likewise go to https://api.slack.com/apps and select the appropriate app from your list of apps. It is then just a matter of adding a new webhook to your channel by doing the following:
- Go to Add features and functionality > Incoming Webhooks and click the Add New Webhook to Workspace button at the bottom.
- You will then need to authorize the connection by selecting the desired channel in the Post to field and pressing Authorize.
As before, you will need to copy the webhook URL from the Webhook URLs for Your Workspace section of the existing page and the OAuth Access Token which you can find under Tokens for Your Workspace by going to the OAuth & Permissions link on the left panel.
Set up Displayr to send an alert to Slack using the slackr R package
Now that we have set up the Slack API webhook to connect to our workspace channel, we can open our Displayr document and proceed to write the R code that will provide the content and send the alert to our intended Slack channel.
The R table in our document is called sign.up.list and displays only new users for each day.
I will now create an R Output via Insert > R Output and paste the below code into the R CODE window:
flipTime::UpdateAt("06-06-2019 23:50", time.zone = "Australia/Sydney", units = "days", frequency = 1, options = "snapshot") x = sign.up.list n = nrow(x) library(slackr) slackr_setup(channel="#api_test", api_token="xxxx", username = "sign_up_alert", icon_emoji = ":heavy_exclamation_mark:", incoming_webhook_url="https://hooks.slack.com/services/xxxxx") today = strftime(Sys.Date(), format="%A, %d %B %y") text_slackr(paste0("*",n,"* new sign-ups for ", today), preformatted = FALSE)
There are four parts to the above code. We need to ascertain the number of records in the table, authenticate via Slack's API, send the message and update this every day at a specific time.
In this code:
- In the first line we are using the flipTime R package to update once a day at 23:50 Sydney time. See here for further information.
- In lines 2 and 3 we declare the R table and n as the number of records in the table
- We then call the slackr R package
- We use slackr_setup to define the channel we want to send to (replace with your channel name), the OAuth API token (replace with the token we saved earlier), the intended username to appear when the message is sent, the accompanying emoji icon (which you can find references for here) and the webhook URL (replace with the URL we copied earlier).
- The second to last line formats today's date using strftime so that it includes the day of the week but this can be amended as required
- The last line creates the message using slackr’s text_slackr function by pasting together n (the number of records) with the date and our message text. The "preformatted" argument set to FALSE allows us to then add basic tags, e.g. * to add bold.
Let's now click Calculate to test the alert is working as expected.
Success! We now have everything set up to receive daily alerts to keep track of new sign-ups.