Let's "talk"

Slack is one the most-used tools for internal communication in companies. By sending direct messages, open channels with colleagues to discuss a certain matter and many more features, you could say you barely even have to talk anymore.

Slack offers a lot of options when it comes to connecting with other services. For example, they have a REST API that allows you to send and receive messages to and from a Slack workspace in your own environment.

As you can imagine, Betty Blocks and Slack make a great team! When using Betty Blocks as a backoffice application, you can send messages for confirmation to others in Slack, for example. 

Quick overview

To integrate your Slack workspace in a Betty Blocks application, we need to do the following things:

  1. Install the Slack Block from the Block Store.
  2. Include a token in the Authorization header. 
  3. Add Http request event in Action.
  4. Select Slack API endpoint to execute desired operation.

Of course, we understand it requires a bit more work than just these 4 steps, but that depends on which operation you're using. In this article we'll discuss a few examples that can be used for educational purpose. 

Read up on the Slack documentation here: Slack API Documentation

In this article we'll show you:

  • How to get a Slack authorization token.
  • How to retrieve a list of all users in workspace.
  • How to send a message to a channel.
  • How to retrieve messages in a channel.

Disclaimer: Understanding the basics of webservices and knowing how to generate custom models is welcome knowledge when starting with these assignments.

Laying the foundation

Each request will make use of your Slack Webservice, where the request itself will be defined by the used Webservice endpoint's path. So before heading onto the webservice endpoints, we need the webservice itself. Installing the Slack Block from the Blocks Store is by far the easiest way, but feel free to add it manually.

If you installed the Slack Block, you already got the webservice, called Slack API. If you're adding it manually, enter the following values in the corresponding fields.

Name: Slack API
Host:
slack.com/api
Protocol:
HTTPS
Authentication Type: None
Request Content-Type:
Other
Response Content-Type:
JSON
Headers:
Authorization

This should leave your webservice looking like:

We're leaving the Authentication Type option on None, as we will be handling the authentication part through the Header variable Authorization. We do need to aquire a token, which will be explained in the next chapter. Save the webservice for now!

Getting an Authorization token

This part can be quite tricky if not done before, but we'll go through it nice and easy. Slack recommends setting up authorization through the header we set up earlier.
This means we have to generate a Bearer token in Slack. 

It starts by adding a redirect URL in Slack that points at a webpage in your app, where 2 input variables are present: code and state. On that webpage, an action is executed that shoots a request at Slack's authentication process. Let's go through it step by step.

  • Add a redirect URL in Slack that corresponds with a webpage in your Betty Blocks app where an action is to be executed.
  • Create the webpage in your Betty Blocks app with the same path as the redirect URL from above.
  • Add 2 input variables: code and state.
  • Create a Webservice endpoint on the Slack webservice called Authorization

Variables

client_id : Is input variable: No
client_secret : Is input variable: No
code : Is input variable: Yes

  • Give the client_id and client_secret Query variables the values from the corresponding credentials found in Basic Information in your Slack workspace.
  • Create a Http request event in your webpage's action, pointing towards the Authorization endpoint. Assign the code Input variable to the code Query variable.
  • With the Betty Blocks webpage + action in place, it's time to execute the last step in Slack. Click on Install App to Workspace and follow the steps. You'll be asked to confirm your identity by posting to an existing channel.
  • After the confirmation is done and the spinner is done spinning, you'll receive a Slackbot notification in Slack and a confirmation email. Most importantly, an OAuth Access Token is now available for you to use in your requests.

Note: The issued OAuth Access Token is based on the user that requested it. This means the permissions regarding the token are tied to the user. For example, posting to a private channel means the user needs access to that channel. More information about Slack OAuth Access Tokens can be found here: Slack OAuth

  • Copy the OAuth Access Token from Slack and use it in your Betty Blocks app:
  1. Save it directly in the Webservice's Authorization header. This requires an additional value in the header, though. The token must be included in the header as following: Bearer xoxp-**********-**********-**********-************************  
  2. Save it in a record to use it dynamically. This way you can connect multiple Slack users that use the same Slack integration. If done this way, the token has to be used in the token Query variable on each endpoint.

For this article, we'll parse it directly in the Authorization header on the Webservice.

Scopes explained

Scopes are a way of making sure the API requests can only access data which is relevant for the destined app. As explained by Slack themselves.

Scopes define the API methods this app is allowed to call, 
and thus which information and capabilities are available on a
workspace it’s installed on. Many scopes are restricted to specific
resources like channels or files.

This means you have to select the required scope to perform a specific request. To find out which scopes you need, take a look at the documentation of the request you want to include in your app.

Examples of Permission Scopes added to perform certain requests:

Click Save Changes to apply the newly added scopes. This does mean, however, you need to reinstall your app each time new scopes are added. A message is shown on the top of the page: 

You've changed the permission scopes your app uses. Please click here 
to reinstall your app for these changes to take effect (and if your
app is listed in the Slack App Directory, you'll need to resubmit it
as well).

Click the Reinstall App button to get this done.

Different operations explained

With the webservice itself in place, it's time to add the endpoints which are used for the actual operations. Because we're using the Slack Block from the Block Store as a base for this article, we'll be using certain names that match the used endpoints included in the Block. If you are adding the endpoint yourself, be sure to pick a good name for the endpoint or just stick with the one we provide in this article.
As each request requires different values, read carefully where to place each parameter. We'll set up a few test actions where we'll perform our requests.

How to retrieve a list of all users in workspace.

This request can be used to collect all users in your Slack workspace.
In this example, we'll retrieve the users and save their values in records.

Slack Method used: users.list

Endpoint: Users: Lists all users in a Slack team
Http method: GET
Path: /users.list

Add a Http request event to your action and select the Users: List all users in a Slack team endpoint. Set user-overview as value for the Response as option.

Now add a Loop event in which we'll go through each member in our response.
Select the members attribute from our Custom model in the Through option and set member_obj as value for the As option.

Within each loop, the iterated object's information can be written to a record.

How to send a message to a channel.

This request can be used to send a message to a channel.
In this example, we'll create an action and use 2 input variables (Text) to determine what message we're going to send (var:message) and to which channel we're sending it (var:channel). 

Slack Method used: chat.postMessage

Endpoint: Messages: Sends a message to a channel
Http method: POST
Path: /chat.postMessage

Add a Http request event to your action and select the Messages: Sends a message to a channel  endpoint. Connect values to the Query variables so a message is successfully sent.

Sending a message as a user: Based on the used OAuth Access Token, Slack will guess which user to send the message with. To use this user, the as_user Query variable will have to be set to true.

Sending a message as a bot: Sending a message as a Bot instead of a user can be useful for notification purposes. To do this, the as_user Query variable will have to be set to false and the username Query variable needs a value to name the Bot.

Click Run and enter values for the input variables.

After the action ran, go check the Slack channel you entered above to see if your message was posted!

How to retrieve messages in a channel.

This request can be used to collect all messages from a channel.
In this example, we'll create an action on a webpage and use 2 input variables to determine from which channel we're collecting the messages (var:channel - kind: Text) and the amount of messages to collect (var:count - kind: Number). Then we'll parse response to a Dynamic table. 

Slack Method used: channels.history

Endpoint: Channels: Fetches history of messages and events from a channel
Http method: GET
Path: /channels.history

Note: This webservice endpoint requires the channel's ID instead of name. This can be found in the URL when viewing the channel in a browser.

Create a webpage (UI Builder) called all-messages. The styling and layout is irrelevant. 

Add 2 input variables to the webpage (var:channel and var:count).
Click Open action in the Settings tab of the Palette.

Add a Http request event to your action and select the Channels: Fetches history of messages and events from a channel  endpoint. Connect values to the Query variables so the messages are successfully collected.

Go back to the Canvas of your webpage and add a Dynamic table component.
Select the messages attribute from the Custom model as source for the Dynamic table.

Assign the values from the messages to different columns and visit the page in a new tab. Make sure the input variables are filled, similar to:

That should have your page looking something like this.

Recap

In this article you learned how to add the Slack webservice to your Betty Blocks app, acquire an access token and how to execute a few requests. For further information about the Slack Web API and how to perform certain operations, take a look at their documentation: Slack API Documentation

Did this answer your question?