Learn how to attach important information into Slack messages using Node.js, Serverless.js, and AWS Lambda shows lots of great details when you copy and paste a link. Go ahead and paste . You’ll see something like this: Slack a link from Medium Slack attaches details to your messages. This is called unfurling. This is called “Link Unfurling” in Slack. For some messages, Slack does this automatically (classic unfurling) and attaches pretty nice details like “Reading Time”. Good news is, you can do this for your links as well! This is especially useful when you need more information or need to retrieve data from a protected source that requires user approval/authentication. When this is the case, you need to get your hands a little dirty and built your own Slack application. In this blog post, you’ll learn how to build your own Slack unfurling application step by step using a real-life example. We will attach details to your OpsGenie alert when you share an OpsGenie alert’s link. For those of you who aren’t familiar, is an incident and on-call management solution for DevOps and ITOps teams. We will use OpsGenie in this example because we have experience using its integrations and API. We also believe that it is very useful to see alert details when you copy and paste a link to reduce context switching between apps. OpsGenie Setting up your environment Before we dive into the development details, let’s prepare your development environment first. As a starter, you need AWS, Slack, and OpsGenie accounts to run this project. We chose Serverless (AWS Lambda) computing service for this project because its pricing is pay-per-trigger and we don’t need to care about the maintenance. It makes a lot of sense for this kind of application where you have possible sparse and low volume requests. We will use Lambda, API Gateway services from AWS, Node.js as the language, and Serverless.js for deploying the project. I’m going to skip npm and Node.js installations. You can google this — and get confused :D Just remember to install Node.js v6.10 or above because this is the version we are going to use in AWS Lambda as it is the latest supported one. To install Serverless.js, run: npm install -g serverless How does the Slack unfurling flow work? As we are done with the initial setup, it is time to learn about the flow of this project. By following the numbers on this diagram, you can learn how our application’s flow works. Application flow One important detail here is Slack’s Events API. We use this API to get notified when an event like a new message or a pin addition to a message happens. Create your Slack application Now, it is time to deep dive into the Slack application part. We will built . Internal integrations are just like regular Slack apps except they can only be installed in your workspace; hence, you don’t need to implement . This is easier and suits better in our use-case. an internal Slack integration OAuth authentication flow First go to link and click “ ” button. Then, you will give your application a name and select the workspace you want the application to exist. Don’t worry, you can change these details later. https://api.slack.com/apps Create New App Create your new Slack app! That is all for now, we will again visit this page once we deploy our function to AWS. Get an API key from OpsGenie if you don’t have one. Create a new API integration under integrations ->API Integration. Get a new account in OpsGenie Create an API integration in OpsGenie One important tip for this function is that we don’t need this API key to update configurations in OpsGenie or send notifications. So, we configure the integration to have read-only access and suppress notifications. Create your Lambda function The easiest way to create your Lambda function is to clone the linked repository below and modify the code as you wish. Then, just install the dependencies. git clone https://github.com/serhatcan/serverless-opsgenie-slack-alert-unfurling cd serverless-opsgenie-slack-alert-unfurling npm install If you want to start from scratch or build your own code, you have three options: Use this project and replace the logic, Use one of the blueprints that AWS Lambda gives you or use AWS CodeStart to have a more complete setup for bigger projects, Run this serverless command to create a new Lambda function: serverless create — template aws-nodejs — path my-service Now, let’s take a look at the main building blocks of our code. Instead of reading from here, you can also take a look at on GitHub. this ~100 lines of code The flow is like this: Check if we passed the right keys to the Lambda function (Slack verification token, Slack access token-API token, and OpsGenie API key) Verify that request comes from Slack by comparing the verification token we have and the received token from the request Check the event payload and the type of the event we received. If event is;- “ ” event: send back the value from the JSON payload because this event means that Slack is checking your endpoint’s health- “ ” event: run the logic url_verification challenge event_callback Now, as we talked about the main building blocks, let’s also talk a little bit about the logic that runs when an event_callback is received. We use Slack and OpsGenie Node.js SDKs to avoid writing boilerplate code while accessing the APIs. The logic part consists of these steps: A message can contain multiple links from our registered domains (app.opsgenie.com in our case). Slack Event API sends these links in an array. We iterate over those links ( ) and run function for each link event.links in payload messageAttachmentFromLink First we extract the alertId using a simple regex from a link like this — yours can support additional case if you’d prefer https://app.opsgenie.com/alert/V2#/show/df2d5224-6df3-4905-a98d-c08c9388f3b5-1516805551907/details Retrieve alert details using the alert ID from OpsGenie Build our Slack message attachment using the details we got Update Slack message with the necessary attachments using Slack API We learned how our function works. But, I suggest you still go ahead and because it would make more sense for most developers. read the code Deploy first version of your Lambda function After creating the Slack app, OpsGenie integration, and writing our function, now it is time to deploy our function. In this step, we will put our function on AWS Lambda but as we still don’t have an API endpoint to tell Slack to make requests, we can’t yet install our app in our workspace. This means that we also don’t have the Slack API key which we’ll get after installing the app. Once we are done deploying our function, we’ll get an HTTPS endpoint from API Gateway service and use it to complete our configuration in Slack. Then, we’ll update our Slack app’s config by setting up the Slack API key and deploy the app once more. One step at a time. So in this step, you should get the verification token from Slack app and paste it in the config in file. We will use this token to verify that requests come from Slack by comparing with the received token. slack_verification_token serverless.yml Slack verification token can be found under Basic information -> App credentials And we also have our OpsGenie API key so, let’s paste it in our config as well. Our configs will look like this (only missing one is as we didn’t install the app in our workspace yet): slack_access_token Our config before we deploy first time Now, we can deploy. Go to your project’s home folder, and run deploy command: serverless deploy All will be handled by Serverless uses AWS CloudFormation to spin up your stack. You can also visit CloudFormation to find out more. serverless.js. CloudFormation Stack Serverless.js created After you run command serverless deploy After you run the command and stack creation is done, you will see an HTTP endpoint in terminal. Copy it and continue with the next part! Configure Slack application You have the API Gateway endpoint. Slack will use this API endpoint to send event details. To tell Slack about this, go to tab. Event Subscriptions Enable and paste the endpoint you got into the “Request URL” input. At this point, Slack will make a request to your endpoint to make sure that it works. No worries, our code knows how to deal with this payload and can return the correct response. events After you get the “ ” sign, now it is time to subscribe some events. Slack will only send the events you subscribe it to. In our case, to get a call to our endpoint when a link contains domain, we need to subscribe to event_._ Verified app.opsgenie.com link_shared Last step in this page is to tell Slack which domains you want to listen. Add domain under App Unfurl Domains part_._ app.opsgenie.com Now, let’s switch to page from the sidebar. In this page, you need to make sure that you have the and scopes. Read scope is necessary for Slack to send the event to us and write scope is necessary for us to update the message with the attachment. Users need to approve this when they install our app. OAuth & Permissions links:read links:write Install your Slack app in your workspace Now, it is time to install the app and get the to access Slack API. Go to page and install it :) OAuth Access Token Install App Click Install App to Workspace Authorize the app After you Authorize the app, you are only one step away from completing the setup! Update your function and deploy one more time After the installation in the page that Slack redirects you, you will see . Copy and paste it in file’s config. OAuth Access Token serverless.yml slack_access_token OAuth Access Token we need to access Slack API Then deploy the app again, run deploy command second time: serverless deploy That is it! ⛱ Let’s try if it works! We need an OpsGenie alert to test our app. You can create one from Slack by typing command or just use the web interface. /genie alert “test my alert” Create a new OpsGenie alert Click the alert details and on the browser, you’ll see an endpoint similar to this: https://app.opsgenie.com/alert/V2#/show/df2d5224-6df3-4905-a98d-c08c9388f3b5-1516805551907/details Copy this link and paste it in Slack and enjoy your work! Enjoy your work! Code is available in this repository: https://github.com/serhatcan/serverless-opsgenie-slack-alert-unfurling Further improvements and tips There are a few things you can do to enhance this integration: Use KMS to securely manage your keys — using environment variables for secret keys isn’t recommended Improve the Slack message with more details, possibly add buttons! If you are thinking about handling more events and want to hide some complexity, you can use Slack Events API module for Node. Slack has and on unfurling. By following these, you can take your app to the next step! pretty good documentation a nice sample on Github References and relevant links https://github.com/serhatcan/serverless-opsgenie-slack-alert-unfurling https://api.slack.com/docs/message-link-unfurling https://github.com/slackapi/sample-app-unfurls Thanks for reading this far! If you enjoyed the tutorial, don’t forget to 👏 to show your support 😃
