aws-ts-slackbot

Slackbot for Posting Slack Mention Notifications

This is an example of a simple Slackbot (called '@mentionbot') that posts a notification to a specific channel any time you're @mentioned anywhere. This bot is useful for when you need a time-ordered list of @mentions to go through at a later point.

Slack users can subscribe/unsubscribe from notifications easily. To receive notifications, add @mentionbot to a channel you want to be notified in. Then send any message to @mentionbot to subscribe. To stop getting messages, send a message to @mentionbot containing the word unsubscribe.

The example contains a few useful patterns showing you how to build a good Slackbot while taking advantage of a lot of conveniences that Pulumi and the aws and awsx packages provide.

1. We set up an ApiGateway API to receive push notifications from Slack whenever important events happen.
2. Slack has strict requirements on how quickly the push endpoint must respond with 200 notifications before they consider the message as "not received", triggering back-off and resending of those same messages. For this reason, our example does not process Slack event messages as they come in. Instead, they are immediately added to an AWS SNS Topic to be processed at a later point in time. This allows the ApiGateway call to return quickly, satisfying Slack's requirements.
3. Two AWS Lambdas are created naturally using simple JavaScript functions. One function is used to create the Lambda that is called when Slack pushes a notification. The other is used to specify the Lamdba that will process the messages added to the Topic. These JavaScript functions can easily access the other Pulumi resources created, avoiding the need to figure out ways to pass Resource ARNs/IDs/etc. to the Lambdas to ensure they can talk to the right resources. If these resources are swapped out in the future (for example, using RDS instead of DynamoDB, or SQS instead of SNS), Pulumi will make sure that the Lambdas were updated properly.
4. Pulumi Secrets provides a simple way to pass important credentials (like your Slack tokens) without having to directly embed them in your application code.

First, we'll set up the Pulumi App. Then, we'll go create and configure a Slack App and Bot to interact with our Pulumi App.

Deploy the App

Note: Some values in this example will be different from run to run. These values are indicated with ***.

Step 1: Create a new stack

$ pulumi stack init mentionbot

Step 2: Set the AWS region

$ pulumi config set aws:region us-east-2

Step 3: Restore NPM modules

Run npm install or yarn install to restore your NPM modules.

Step 4: Preview and deploy your app

Run pulumi up to preview and deploy your AWS resources.

$ pulumi up
Previewing update (mentionbot):
...

    Do you want to perform this update? yes
    Updating (mentionbot):

         Type                                Name                          Status 
     +   pulumi:pulumi:Stack                 aws-ts-slack-mentionbot       created
     +   ├─ aws:sns:TopicEventSubscription   processTopicMessage           created
     +   │  ├─ aws:iam:Role                  processTopicMessage           created
     +   │  ├─ aws:iam:RolePolicyAttachment  processTopicMessage-32be53a2  created
     +   │  ├─ aws:lambda:Function           processTopicMessage           created
     +   │  ├─ aws:sns:TopicSubscription     processTopicMessage           created
     +   │  └─ aws:lambda:Permission         processTopicMessage           created
     +   ├─ aws:apigateway:x:API             mentionbot                    created
     +   │  ├─ aws:iam:Role                  mentionbot8e3f228c            created
     +   │  ├─ aws:iam:RolePolicyAttachment  mentionbot8e3f228c-32be53a2   created
     +   │  ├─ aws:lambda:Function           mentionbot8e3f228c            created
     +   │  ├─ aws:apigateway:RestApi        mentionbot                    created
     +   │  ├─ aws:apigateway:Deployment     mentionbot                    created
     +   │  ├─ aws:lambda:Permission         mentionbot-89b3ba11           created
     +   │  └─ aws:apigateway:Stage          mentionbot                    created
     +   ├─ aws:dynamodb:Table               subscriptions                 created
     +   └─ aws:sns:Topic                    messages                      created

    Outputs:
        url: "https://***.execute-api.us-east-2.amazonaws.com/stage/"

    Resources:
        + 17 created

    Duration: 25s

    Permalink: https://app.pulumi.com/***/mentionbot/updates/1

Step 5: Create a new Slackbot

To create a new Slackbot, first go to https://api.slack.com/apps and create an account if necessary. Next, click on 'Create New App' here:

Pick your desired name for the app, and the Workspace the app belongs to. Here we choose MentionBot:

Once created, you will need to 'Add features and functionality' to your app. You'll eventually need all these configured:

First, we'll enable 'Incoming Webhooks'. This allows your Slack bot to post messages into Slack for you:

Next, create a bot user like so:

Next, we'll enable 'Event Subscriptions'. This will tell Slack to push events to your ApiGateway endpoint when changes happen. Note that we put the Stack-Output url shown above (along with the events suffix). This corresponds to the specific ApiGateway Route that was defined in the Pulumi app. Note that Slack will test this endpoint to ensure it is accepting Slack notifications and responding to them in a valid manner. We'll also setup notifications for the events we care about. Importantly, our bot will have to hear about when people mention it (for subscribing/unsubscribing), as well as hearing about all messages (so it can look for @-mentions):

Next, we'll go to 'Permissions'. Here, we can find the oauth tokens your Pulumi App will need. Specifically, we'll need the 'Bot User Oauth Token' listed here:

Underneath this, we'll set the following Scopes defining the permissions of the bot:

Now, we're almost done. The only thing left to do is supply your Pulumi App with the appropriate secrets/tokens. We'll need the Bot Oauth token (shown above), and the 'Verification Token' (found under 'Basic Information'):

Supply these both like so:

$ pulumi config set --secret mentionbot:slackToken xoxb-...
$ pulumi config set --secret mentionbot:verificationToken d...

Next, install the Slack App into your workspace:

And we're done!

Step 6: Interact with the Slackbot

From Slack you can now create your own private channel:

Invite the bot to the channel:

Then send it a message. Note that it may take several seconds for the bot to respond due to Slack push notification delays, SNS Topic delays, and Slack incoming message delays.

And you're set! From now on when someone mentions you, you'll get a little message in your channel like so:

Clean up

1. Run pulumi destroy to tear down all resources.

2. To delete the stack itself, run pulumi stack rm. Note that this command deletes all deployment history from the Pulumi Console.