README.md

slack-link-unfurling

Guide on how to implement link unfurling in slack

Getting Started

These instructions will guide you on controlling unfurling of links tied to your domain(s).

Prerequisites

You'll need the following tools to setup your environment:

• Node.js
• Ngrok
• Slack

Setting up back-end

1. Clone the repo
2. Run npm install to install all the packages
3. Run npm run-script run to start up the node app
4. In a separate command console run ./ngrok http 1337

Setting up Slack App

1. Go to Step 1 - Your Apps page
2. Click on Create New App
   
3. Set the App Name and select the workspace to Develop the app
   
4. Copy the Client ID, Client Secret and Signing Secret values to config.json file
   
5. Click on Event Subscriptions
   
6. Enable Events
   
7. Set the Request URL to be ngrok's session url
   
   • You should see a ping from Slack verifying the endpoint and once that is done, you should see Verified above the Request URL field
8. Subscribe to Link Shared event
   
9. Add the domains you want to be notified of when shared
   
10. Save the changes to Event Subscriptions, it should look like this:
    
11. Click on Bot Users - Need this for the botkit library we are using to interface with Slack
    
12. Fill out the bot user info
    
13. Click on OAuth & Permissions to set up the Scopes and get Tokens
    
14. Add the following to Permission Scopes:
    • links:write
    • team:read
15. Click on Install App to Workspace to add the App to your workspace
    
16. Verify the permissions request by the app and authorize the app
    
17. Copy the OAuth Access Token and Bot User OAuth Access Token to the config.json file
    
18. From your Slack channel (any!) type in http://example.com and see it unfurl!
    
    • Incoming request from Slack
      
    • Outgoing response to Slack
      
19. Now try passing http://example.com https://example.com
    
    • Slack sends back both urls in the links array
    • Incoming request from Slack
      

Future proofing link unfurling

Currently in LinkSharedHandler.js the following block of code explicitly handles cases of one and two urls:

const unfurls = {};

unfurls[message.event.links[0].url] = {
    'text': 'testing 1',
};

if (message.event.links.length > 1) {
    unfurls[message.event.links[1].url] = {
        'title': 'testing 2',
        'title_link': 'https://example.com',
        'text': 'testing 2',
        'fields': [
            {
                'title': 'Testing 2',
                'value': 10,
                'short': true
            }
        ],
        'actions': [
            {
                'name': 'Testing',
                'text': 'Testing 2',
                'type': 'button',
                'value': 'testing'
            }
        ]
    };
}

This is done purely to demonstrate sending back of simple text message for the first link and an interactive message for the second link if one is passed.
More often than not you'll have same format for urls matching specific domains so processing of the links can be done via map function.

Reading Resources

• Slack link unfurling
• Botkit
• PM2

TODO

Need to add testing! I have tried out botkit-mock but was unable to figure out how to set up track events :\

License

This project is licensed under the MIT License - see the LICENSE.md file for details