Parser

This is a serverless Slack Bot that uses Postlight's mercury parser to display the parsed content directly in your slack channel! So instead of sending a link to a certain article that will open in a new browser window, you will be sending the article as a readable post directly.

Once everything is set, use it as follows:

/parser <url>

Development

This repo is based on Postlight's serverless-babel-starter. You can refer to it for serverless development documentation.

Setting up the workspace

clone this repo:

git clone https://github.com/postlight/slash-mercury-parser.git

Install dependencies:

yarn install

Creating your Slack Bot

Create a new slack app here and link it to your development slack workspace.

Under Add feature and functionality:

Add a bot:
- Click on Bots
- Click on Add a bot User
- Enter a Display name and Default username
- Click on Add bot User
Add a slash command
- Click on Slash Commands
- Click on Create New Command
- Enter /parser, https://example.com/invoke, and Renders the parsed content for Command, Request URL, and Short Description
- Click on Save

NOTE: you will fill in a correct Request URL once you deploy your functions. You can leave it as is for now.

Environment variables

After you've installed the bot in your slack workspace, navigate to Install App under Settings and copy your Bot User OAuth Access Token. This token will be used to verify the slack API call.

Create a secrets.json file in the project root and add the following:

{
  "SLACK_AUTH_TOKEN": "xxxx-YOUR-ACCESS-TOKEN"
}

Deploying the functions

yarn deploy:env

Windows users should modify the deploy scripts as follows:

{
  "deploy:dev": "sls deploy --stage dev",
  "deploy:stage": "sls deploy --stage stage",
  "deploy:production": "sls deploy --stage production"
}

NOTE: save your /post URL when the deployment is complete. It looks like this: https://xxxxxxx.execute-api.region.amazonaws.com/env/invoke and replace your Request URL with it.

Testing the bot

Inside a public channel in your slack workspace, invoke the bot using:

/parser <url>

You should see a Parsing your article .. message which is only visible to you, followed by a bot response of the parsed content as a post.

The logic behind a slack bot

Whenever the slash command is executed, slack makes a POST request to your app via the Request URL that was set.
Your logic will get executed and will invoke a slack API call.
Slack expects a response within 3 seconds
Slack API Documentation

The logic behind the parser bot

Since Slack expects an OK response within 3 seconds, the first lambda function ./src/invoke.js checks for any errors in the URL, fetches the content from mercury, and invokes the second function ./src/uploadPost.js. The second function is responsible for hitting the slack API and sending the post. If an error occurs, the user will be notified.

For example, /parser blabla will result in this error:

Contributing

Unless it is explicitly stated otherwise, any contribution intentionally submitted for inclusion in the work, as defined in the Apache-2.0 license, shall be dual licensed as above without any additional terms or conditions.

🔬 A Labs project from your friends at Postlight