├── .github └── CODE_OF_CONDUCT.md ├── .gitignore ├── README.md ├── package.json └── src ├── index.js └── onboarding.json /.github/CODE_OF_CONDUCT.md: -------------------------------------------------------------------------------- 1 | # Code of Conduct 2 | 3 | ## Introduction 4 | 5 | Diversity and inclusion make our community strong. We encourage participation from the most varied and diverse backgrounds possible and want to be very clear about where we stand. 6 | 7 | Our goal is to maintain a safe, helpful and friendly community for everyone, regardless of experience, gender identity and expression, sexual orientation, disability, personal appearance, body size, race, ethnicity, age, religion, nationality, or other defining characteristic. 8 | 9 | This code and related procedures also apply to unacceptable behavior occurring outside the scope of community activities, in all community venues (online and in-person) as well as in all one-on-one communications, and anywhere such behavior has the potential to adversely affect the safety and well-being of community members. 10 | 11 | For more information on our code of conduct, please visit [https://slackhq.github.io/code-of-conduct](https://slackhq.github.io/code-of-conduct) -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | .DS_Store 2 | node_modules 3 | .env 4 | *.log -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Slack Onboarding Example 2 | This project demonstrates how to build an Onboarding App using Slack's Events API. It's meant to serve only as an example through code. 3 | 4 | ![onboarding](https://cloud.githubusercontent.com/assets/35968/17162650/5703766c-537d-11e6-9c36-3e780d06f77c.gif) 5 | 6 | ## Setup 7 | ### [Create an App](https://api.slack.com/apps/new) 8 | 9 | ![](https://cloud.githubusercontent.com/assets/35968/17163271/355323a4-5383-11e6-93fc-e1f74641e553.png) 10 | 11 | 12 | ### Enable the Events 13 | ![](https://cloud.githubusercontent.com/assets/35968/17162944/27e8f6ec-5380-11e6-8d83-6e6ada06e536.png) 14 | 15 | 16 | ## Updating the Script 17 | The onboarding script is driven by [onboarding.json](src/onboarding.json). The app looks for events that match the `event` property in this JSON and [marks it complete](src/index.js#L25). 18 | 19 | ```json 20 | { 21 | "welcome": { 22 | "text": "Welcome to Slack! Get started by completing the steps below.", 23 | "attachments": [ 24 | { 25 | "event": "star_added", 26 | "title": "Star a Message", 27 | "title_link": "https://get.slack.help/hc/en-us/articles/201331016-Using-stars", 28 | "text": "Stars are a way to mark an item in Slack as important. You can star channels or direct messages to move them to the top of your left sidebar, or star messages so you can easily come back to them later." 29 | }, 30 | { 31 | "event": "reaction_added", 32 | "title": "Respond With a Reaction Emoji", 33 | "title_link": "https://get.slack.help/hc/en-us/articles/206870317-Emoji-reactions", 34 | "text": "You can quickly respond to any message on Slack with an emoji reaction. Reactions can be used for any purpose: voting, checking off to-do items, showing excitement." 35 | }, 36 | { 37 | "event": "pin_added", 38 | "title": "Pin a Message", 39 | "title_link": "https://get.slack.help/hc/en-us/articles/205239997-Pinning-messages-and-files", 40 | "text": "Important messages and files can be pinned to the details pane in any channel or direct message, including group messages, for easy reference." 41 | } 42 | ] 43 | } 44 | } 45 | ``` 46 | 47 | ## Running Locally 48 | 49 | ### Environment 50 | This app requires two environment variables. 51 | 52 | * `TOKEN` - The Slack token used to post messages 53 | * `PORT` - The port to host the webserver on 54 | 55 | 56 | 57 | ### WebServer 58 | ```bash 59 | npm install 60 | npm start 61 | ``` 62 | ### Tunneling 63 | Using [ngrok](https://ngrok.com/) you can port a public url to your local server. After installing ngrok, you can get a url by running: 64 | 65 | ```bash 66 | ngrok http 3000 67 | ``` 68 | 69 | You should get a response like this: 70 | 71 | ```bash 72 | Tunnel Status online 73 | Version 2.1.3 74 | Region United States (us) 75 | 76 | Web Interface http://127.0.0.1:4040 77 | Forwarding http://d8ab065c.ngrok.io -> localhost:3000 78 | Forwarding https://d8ab065c.ngrok.io -> localhost:3000 79 | 80 | Connections ttl opn rt1 rt5 p50 p90 81 | 0 0 0.00 0.00 0.00 0.00 82 | ``` 83 | 84 | Use the `Forwarding` url as the *base url* of your `Request URL` on Slack's Event Subscription page. 85 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "slack-onboarding-example", 3 | "version": "1.0.0", 4 | "description": "Example onboarding bot using Slack's Event API", 5 | "scripts": { 6 | "start": "node src/index.js" 7 | }, 8 | "author": "John Agan ", 9 | "dependencies": { 10 | "tinyspeck": "^1.0.3" 11 | } 12 | } 13 | -------------------------------------------------------------------------------- /src/index.js: -------------------------------------------------------------------------------- 1 | const ts = require('tinyspeck'), 2 | onboarding = require('./onboarding.json'), 3 | {PORT, TOKEN} = process.env, 4 | users = {}; 5 | 6 | 7 | // setting defaults for all Slack API calls 8 | let slack = ts.instance({ token: TOKEN }); 9 | 10 | 11 | // build the user's current onboarding message 12 | function getStatusMessage(user) { 13 | return Object.assign({ channel: user }, onboarding.welcome, users[user]); 14 | } 15 | 16 | 17 | // watch for onboarding slash commands 18 | slack.on('/onboarding', payload => { 19 | let {user_id, response_url} = payload; 20 | let message = getStatusMessage(user_id); 21 | 22 | // send current onboarding status privately 23 | slack.send(response_url, message); 24 | }); 25 | 26 | 27 | // event handler 28 | slack.on('star_added', 'pin_added', 'reaction_added', payload => { 29 | let {type, user, item} = payload.event; 30 | 31 | // get the user's current onboarding message 32 | let message = getStatusMessage(user); 33 | 34 | 35 | // modify completed step 36 | message.attachments.forEach(step => { 37 | if (step.event === type && !step.completed) { 38 | step.title += " :white_check_mark:"; 39 | step.color = "#2ab27b"; 40 | step.completed = true; 41 | } 42 | }); 43 | 44 | 45 | // save the message and update the timestamp 46 | slack.send(message).then(res => { 47 | let {ts, channel} = res.data; 48 | users[user] = Object.assign({}, message, { ts: ts, channel: channel }); 49 | }); 50 | }); 51 | 52 | 53 | // incoming http requests 54 | slack.listen(PORT); 55 | -------------------------------------------------------------------------------- /src/onboarding.json: -------------------------------------------------------------------------------- 1 | { 2 | "welcome": { 3 | "text": "Welcome to Slack! Get started by completing the steps below.", 4 | "attachments": [ 5 | { 6 | "event": "star_added", 7 | "title": "Star a Message", 8 | "title_link": "https://get.slack.help/hc/en-us/articles/201331016-Using-stars", 9 | "text": "Stars are a way to mark an item in Slack as important. You can star channels or direct messages to move them to the top of your left sidebar, or star messages so you can easily come back to them later." 10 | }, 11 | { 12 | "event": "reaction_added", 13 | "title": "Respond With a Reaction Emoji", 14 | "title_link": "https://get.slack.help/hc/en-us/articles/206870317-Emoji-reactions", 15 | "text": "You can quickly respond to any message on Slack with an emoji reaction. Reactions can be used for any purpose: voting, checking off to-do items, showing excitement." 16 | }, 17 | { 18 | "event": "pin_added", 19 | "title": "Pin a Message", 20 | "title_link": "https://get.slack.help/hc/en-us/articles/205239997-Pinning-messages-and-files", 21 | "text": "Important messages and files can be pinned to the details pane in any channel or direct message, including group messages, for easy reference." 22 | } 23 | ] 24 | } 25 | } --------------------------------------------------------------------------------