Skip to content

Latest commit

 

History

History
125 lines (105 loc) · 5.29 KB

README.md

File metadata and controls

125 lines (105 loc) · 5.29 KB

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:

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
    Step 2 - Create New App
  3. Set the App Name and select the workspace to Develop the app
    Step 3 - Set App Name and workspace
  4. Copy the Client ID, Client Secret and Signing Secret values to config.json file
    Step 4 - Copy over credentials
  5. Click on Event Subscriptions
    Step 5 - Event Subscriptions
  6. Enable Events
    Step 6 - Enable events Events enabled
  7. Set the Request URL to be ngrok's session url
    Step 7 - Events Request 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 Ngrok session
  8. Subscribe to Link Shared event
    Step 8 - Subscribe to Link Shared event link_shared event
  9. Add the domains you want to be notified of when shared
    Step 9 - Add domains to monitor
  10. Save the changes to Event Subscriptions, it should look like this:
    Step 10 - Save Event Subscriptions
  11. Click on Bot Users - Need this for the botkit library we are using to interface with Slack
    Step 11 - Setup Bot Users
  12. Fill out the bot user info
    Step 12 - Fill out bot user info
  13. Click on OAuth & Permissions to set up the Scopes and get Tokens
    Step 13 - Scopes and Tokens
  14. Add the following to Permission Scopes:
    • links:write
    • team:read Step 14 - Scope update
  15. Click on Install App to Workspace to add the App to your workspace
    Step 15 - Add app to workspace
  16. Verify the permissions request by the app and authorize the app
    Step 16 - Verify and Authorize app
  17. Copy the OAuth Access Token and Bot User OAuth Access Token to the config.json file
    Step 17 - Copy over tokens
  18. From your Slack channel (any!) type in http://example.com and see it unfurl!
    Step 18 - Test unfurl a single link
    • Incoming request from Slack
      Request from Slack
    • Outgoing response to Slack
      Response to Slack
  19. Now try passing http://example.com https://example.com
    Step 19 - Test unfurling 2 links
    • Slack sends back both urls in the links array
    • Incoming request from Slack
      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

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