Our Woby portal now supports Slack integration. This means that you are able to connect your slack workspace with the Woby portal in order to receive notifications in Slack about new orders, approve them and get reminders of unapproved orders. In order to make use of this integration, there are a few steps to follow before you can make use of this functionality. In this document we will guide you step-by-step on how to enable this integration.
Step 1: Creating an App.
What we mean by creating an App is allowing our Portal to communicate with a Slack Workspace and Channels. You can see it as a communication layer between Slack and the Portal.
In order to create an App for Slack go to https://api.slack.com/ and click on Create an app, or you can go directly to https://api.slack.com/apps (given you are already logged in to slack.com).
When you are on this page you’ll see a big green button saying: “Create an App” click this or click “From scratch” if you are seeing a popup.
In the pop-up give the App a name. We will call it Woby Notifier. You could name it anything you want but in order to quickly recognize which apps are installed and what they’re doing, we recommend keeping the name “Woby Notifier”. However we cannot stop you from naming it differently. After naming the app, pick a Workspace from the drop-down in the field below the App Name. In our example we have a Workspace called Woby Test Workspace and will keep using this in this guide. When done, click “Create App”.
After creating the App you’ll be redirected to a page called Basic Information. On this page you’ll find most of the stuff we will need to configure in order to make the integration work.
Scroll down until you see the section Add features and functionality. In this section you’ll see 6 cards and we are going to need 3 of them.
First, click on Bots. This feature allows us to send commands and messages to Channels within your workspace. When on the App Home page, you’ll see a green button called Review Scopes to Add. Click this button. When you’ve clicked the button, you’ll be presented a page called OAuth & Permissions. This page will tell Slack which permissions the bot should have. Think about: can my bot send messages, respond to user messages, interact with messages, etc.
Scroll down on this page until the section Scopes appears. This section will give the bot permission to certain actions (scopes). In the sub-section Bot Token Scopes, click on “Add an OAth Scope”. When clicked a dropdown will be presented. The following scopes need to be added:
- channels:join
- chat:write
- chat:write.public
- groups:write
- incoming-webhook
To read about what these scopes do, go to: https://api.slack.com/scopes.
For now, this concludes the Bot configuration.
Step 2 activate Interactivity
Next up is activating Interactivity. This feature allows a message with a button to be sent and interacted with. In our cases we use this feature to approve new orders. In order to activate this, you can click on Interactivity & Shortcuts in the sidebar, or click on Interactive Components in the Add features and Functionality section on the Basic Information page.
When clicked, a page called Interactivity & Shortcuts will appear. In the section Interactivity click the badge Off to turn it on.
The badge will turn green and an input field Request URL will appear. In this input field we’ll add the following URL: https://portal.woby.nl/api/v1/slackUserInteraction. This URL is a handler to receive user interactions with buttons clicked in Slack Messages sent by the App.
Now click on Save Changes at the bottom of the page and we are done with the Interactivity part.
The configuration process is now complete. To add the app to the workspace, navigate back to the Basic Information page by selecting it from the sidebar. On this page, there will be a button labeled “Install to Workspace”, click it. You will be redirected to a page where you can grant the app access to your workspace. To ensure that the permissions are set correctly, verify by clicking "Perform actions in channels & conversations". The next step is to add a channel for the app to post to, this can be done by selecting one from the drop-down menu in the "Where should Woby Notifier post?" section. For the purpose of this guide, a channel called "slack-integration" has been created. But any channel can be chosen. Once a channel is selected, click "Allow."
And that’s it! You’ve now created a Slack App.
If you open Slack you’ll see in the sidebar under the section Apps an app called Woby Notifier and you’ve also received a new message in your selected channel. This message notifies everyone in the channel the App has been integrated into Slack.
Step 3 : Configuring the portal.
Before we can send messages to this channel we need to add some keys to the portal. Those keys are needed to identify the App, Channel and Workspace.
Important note! Never! Ever! share the credentials with other people. If you don’t remember them simply go back to api.slack.com.
In the portal go to the establishment settings, click “Slack integration” in the sidebar. Check the checkbox Use Slack integration. When you’ve enabled this feature we are going to need some keys in order to make the integration work.
Getting the keys
Back on api.slack.com, go to OAuth & Permissions. This page has changed since we were here last time, now a field has appeared with what appears to be some random gibberish. This gibberish is actually the Bot Token, this token is needed to tell slack that this bot is authorized to interact with your Workspace and Channels. Copy this value and paste it into the input field Bot OAuth Token in the Woby portal.
Next up is the Signing Secret. This key will be used to identify if a user interaction with a message is truly from your workspace. This prevents bad actors from interacting with unapproved orders and/or with your Workspace and channels. The Signing Secret can be found on the page Basic Information under the section App Credentials. Click on “Show” at Signing Secret and copy the value and paste it in the field Signing Secret in the portal.
Now that we have the tokens we need to connect to the Workspace and identify legitimate interactions, we need to tell the portal where the messages need to be sent. The key we need is called a Channel ID. This is a unique identifier for your channel within your Workspace. To get this key, simply go to slack and right-click on the channel where you wish to send the messages to. Click on View channel details and scroll to the bottom and copy the Channel ID. After you’ve copied this value paste it in the Channel ID input field in the portal.
Now you are done setting up the portal you can click save and the integration is finished!
Explaining the messages
Once the integration is complete, you can start to receive the messages. This chapter will explain a little bit about the messages sent by the Portal.
When a new order is placed, a message will be sent to the chosen channel. This message will contain the Order ID, Time of order and an “Approve” button.
The portal will send a new message every ~20 seconds until the order is approved. This message contains a list of all still-to-be-approved orders. It may occur that the messages will be incredibly long or a lot of messages have been sent. It would be a bit of a hassle to scroll all the way back to the top to Approve the order. To make it more convenient, this message contains a “Jump to order” link per unapproved order. When clicking this, Slack will scroll to the original message so you can approve it.
When the Order is approved the original message will change from a button to a string, letting people know the order has been accepted, by whom and at what time. When the order is approved, it will also disappear from the Non-approved orders message list when a new one is sent. When all the orders are accepted, no new message will be sent until a new unapproved order is found.