API monetization is a growing trend. It is now a consolidated business of digital companies to grant access, for a fee, to the APIs providing company data or to some services using different distribution channels.
A possible channel for spreading your APIs and services is integration with existing and well-known platforms, such as Slack. If your service or APIs can be useful and valuable in the context of a meeting, a project chat or during customer care activities, then creating an integration for Slack could prove profitable.
But what’s behind the integration of existing APIs with Slack? How complex is it to publish the classic “Add to Slack” button on your website? Let’s see it in this step-by-step guide.
Create an App
In Slack you can create your own apps or use existing ones. The most complete and professional ones are listed in the App Directory. You will find everything from integration with Google Calendar to Zoom and GitHub. Normally apps allow you to add functionality to your channels, providing integration with existing services. An app can communicate with participants in a channel by sending suggestion messages and notifications or by responding to specific commands. The app can “express itself” in the form of a bot or act as you, sending messages directly. In short: the potential is unlimited!
Creating your own app is simple: just reach the API portal and follow the directions of “Create New App”.
Before going into the next steps of creating an app, it is better to clarify how this can be distributed on Slack.
Installation in your Workspace
By default, when we create an App on Slack, it can be installed on your workspace. Anyone invited to participate in the same workplace can therefore interact and take advantage of it. If we intend to create an application dedicated exclusively to our team, no further effort is required.
If the app we intend to create must be able to be installed and shared on other workspaces, for example at company level, it is necessary to activate the “distribution” of the application. This allows the creation of the classic “Add to Slack” button and involves the implementation of an OAuth 2.0 flow to manage the authorization process.
The App Directory is a kind of Slack marketplace where they are listed (by category) all applications that have passed a verification process. It’s conducted directly by a Slack team that ensures that the application has the necessary technical and quality requirements. It is obvious that if we intend to monetize our APIs through an integration, publication on the App Directory will allow us to have a much wider audience and better reputation, because already verified by Slack itself.
Publishing your app in the official Directory is obviously a more complex process, which involves a long list of requirements to be met.
We created our app, which however does not yet perform any function. Depending on the service we want to integrate into Slack, first it is better to define how our application will interact on Slack channels. There are several possibilities: the app can be invoked with a “slash command” or in the case of specific events.
The “slash commands” are the typical Slack commands preceded by a slash such as, for example / INVITE . In the case of events, it is possible to call the app when it is mentioned (@app_name) during a conversation or when direct messages are sent to it.
Personally I chose this second approach, based on events, but it’s not a single, optimal solution: it depends on the service we are integrating and on the UX that we want to provide. Furthermore, nobody forbids us to foresee both ways.
How to integrate our service and its existing APIs? It will be necessary to create a dedicated layer , able to respond to Slack’s requests and interact with users, on the one hand, and able to call our APIs on the other side.
What should this integration layer do? Let’s see:
- Receive events from Slack and respond accordingly, providing the service provided by our APIs
- Manage the OAuth 2.0 authorization process
- Manage subscription and billing o integrate with an E-Commerce platform
Subscription to events
We have choosen to receive notifications when an event of interest to our app occurs. It’s required to specify our integration layer endpoint.
Integration layer must reply to the request using the challenge parameter as indicated to validate our endpoint. After setting it we can specify which notifications we want to receive.
The events are well described: message.im occurs, for example, when a direct message is sent to our app, typically in the app private channel.
The concept of Scope is important to understand: in order to receive some notifications it is necessary that our application has obtained authorization for a particular scope; in the previous example, im: history . We will see that this authorization will be requested during the app authorization process.
Is that all? Not yet. It is also appropriate to make sure that our integration layer verifies the origin of the requests: we certainly do not want to publish a paid service and be defrauded right?
The request verification algorithm is indicated in this article from the official documentation. Requires the use of the Signing Secret , a parameter that Slack attributes to each application and which can be found in the App Credentials section of your application.
Personally, I took care of creating a totally serverless integration layer, using API Gateway and AWS Lambda. Here is an example of the event subscriber function, including Base64 decoding and Slack signature verification.
Notifications are in JSON format and well documented. An example of a payload for message: im is here.
What is the app_home_opened event? It occurs when the user opens the app section and can be used to send a welcome message and to explain, for example, how to use the app. It is good to remember this event because its correct management is one of the requirements for publication in the App Directory.
Available events are many and allow you to customize the UX of your integration .
The OAuth 2.0 authorization process is documented very clearly.
Authorization process consists of the following steps:
- User starts the installation process by clicking on “Add to Slack”. HTML code of the button can be easily obtained from the app page. URL called by the button need to be managed by our integration layer which will redirect (302) to the Slack authorization URL (https://slack.com/oauth/v2/authorize) specifying required parameters client_id and scope. First parameter identifies our app and its value is available in the App Credentials section. The second specifies the various authorizations that we intend to request for our app (scope).
- The user authorizes the installation of the application
- A first authorization code is provided to our integration layer at the redirect URL specified in the OAuth & Permissions section of our application
- The integration layer takes care of requesting the authorization token by calling the dedicated URL (https://slack.com/api/oauth.v2.access) and specifying the client_id and client_secret parameters, in addition to the code just obtained
- If the answer is positive, the token is stored by the integration layer so that it can be used to interact with the related workspace.
Here is an example of a Lambda function able to manage the process, storing the OAuth tokens in a DynamoDB table.
UX & Billing
Are we done? No, we’re just at the beginning! We have created two functions, the first of which is able to receive notifications about the events that we are interested in managing with our app. The second is responsible for correctly managing the authorization process.
We must now roll up our sleeves and implement real integration between Slack and our service or API. The Python package slackclient allows us to interact with the Web Client API in a way you can, for example, post a message in response to a specific direct command. As mentioned at the beginning of this post, the possibilities are endless and depend a lot on the service you want to integrate.
Slack messages can be enriched with elements to make them more functional and attractive. The structure of each message is made up of blocks. The excellent editor allows you to experiment with the layout of messages before implement them in your app.
We will also have to manage integration with the E-Commerce platform in order to manage subscriptions to our service. I personally used Paddle, an all-in-one SaaS commerce platform.
Publishing on the App Directory
Is our App ready? Have we tested its functionality, the installation process and integration with the E-Commerce platform? Very well! Are we ready for publication in the App Directory? Again, not yet.
The publication process involves the verification by the Slack team of a series of requirements that our App must satisfy. There are many, divided into sections and which I recommend reading carefully.
The verification process is very painstaking and it can take a few days to get feedback. If even one of the requirements is not met, it is reported and a new submission must be made, obviously after correcting your app.
If we have done everything correctly, our app will finally be present in the Slack Directory and we will start monetizing our service .. or at least we hope!
Did we have fun? See you next time!