<img src="http://i.imgur.com/6Vk0cZX.png">
Welcome, traveler. I've been waiting for you.
[You have?]<2|
(click: ?2)[Yeah, I'm your Magic Rock. Some folks at <a href="http://www.tinyspeck.com" target="_blank">Tiny Speck</a> created me a long time ago, and I stuck around to help people out.
[My magic what?]<3|]
(click: ?3)[Just roll with it. I'm here to help. Anyway, I heard you wanted to learn about the <a href="http://api.slack.com" target="_blank">Slack API</a> and slash commands. In this tutorial, you're going to create an app called Foodme. Never again will you suffer the pangs of hunger and the dilemma of choice at the same time! Just use Foodme to create weird and wonderful new menu ideas for your next meal, party, or work event. Ready to get started?
[Wait, what's a slash command?]<what|]
(click: ?what)[### Slash Commands
A slash command is like a command-line interface into Slack. You can pass it certain commands and it will respond to you. You can make slash commands to do all kinds of stuff, like checking the weather, creating reminders, and setting alarms. In this project, you can type <pre>/foodme</pre> and get a new meal idea every time. Plus, your coworkers will think you're a wizard. ✨
Slack has a couple slash commands built in. Go try one like <pre>/shrug</pre>. I'll wait.
[Neat!]<4|]
(click: ?4)[### Dependencies
Okay. So first things first, you're going to need some supplies. Think of it like gearing up for an epic quest. Make sure you have this stuff then come back and let me know so we can move on.
* <a href="https://nodejs.org/en/download/package-manager/" target="_blank">Node.js</a>
* <a href="https://localtunnel.github.io/www/" target="_blank">Localtunnel</a>: This will let us test our bot locally. Just use <pre>npm install -g localtunnel</pre>. We'll need to move it later for production, but for now, this works. It's super easy and fast, and supports HTTPS. That will be important later.
[I've collected everything I need.]<5|]
(click: ?5)[Great! Now if you go over and fork then clone <a href="https://github.com/nelsonam/foodme" target="_blank">this GitHub repo</a>, it should give you a starting template. Once you have it on your machine, run <pre>npm install</pre> to install the dependencies. One of the packages we're going to be using is called Botkit. Despite its name, it does a lot of the hard work of connecting to the Slack API, and doesn't have to be used for just bots.
After running <pre>npm install</pre>, you should edit your <pre>package.json</pre> file to name your slash command and update the GitHub URLs.
[Done and done.]<6|]
(click: ?6)[🙌 Time to get down to the good stuff.
### Connect your app to the Internet
You could run commands all day on your local machine, but they won't do a thing until they have a request URL to handle them. The Slack API requires a secure HTTP connection, a.k.a. HTTPS. Localtunnel does this for us, but when you deploy your app elsewhere, keep this in mind.
To open up a connection on our laptop, run localtunnel on port 4201 like so:
<code>lt --port 4201 --subdomain foodme</code>
While localtunnel is running, you'll see some stats about where you can find it on the web. Using the settings above, this will be <a href="https://foodme.localtunnel.me:4201" target="_blank">https://foodme.localtunnel.me:4201</a>
[Tunneled!]<7|]
(click: ?7)[### New app, who dis?
Once you've got that set up, you need to tell Slack about it. Head over to <a href="https://api.slack.com/applications/new" target="_blank">https://api.slack.com/applications/new</a> to create a new app.
Select 'Permissions' in the 'Add features and functionality' section, then add your new shiny address as the Redirect URL.
<code>https://foodme.localtunnel.me/oauth</code>
<img src="http://i.imgur.com/zR6bacQ.png">
After that, head back to the 'Basic Information' section and choose 'Add features and functionality'. Since we're making a slash command, select 'Slash Commands'.
Create a new command and use the settings below.
<img src="http://i.imgur.com/NMoAKHK.png">
The command is <pre>/foodme</pre>, because that's what we're going to type into Slack to start the process. The Request URL looks like this:
<code>https://foodme.localtunnel.me/slack/receive</code>
What's cool about this is that this single URL can receive any slash command coming from Botkit. Woo! (Go give the folks at <a href="https://howdy.ai/botkit/" target="_blank">Howdy.ai</a> a high-five.)
[What's next?]<8|]
(click: ?8)[### Tokens and IDs and Secrets! 😱
After saving that slash command, Slack gives us a Verification Token. This is like knowing the special knock for a secret society. Slack checks this to make sure our request is really coming from Slack and not somewhere else. Don't tell anyone what your Verification Token is! You get one Token per app, so if you have multiple commands they will share.
To find this new Token, navigate back to 'Basic Information' and scroll down until you see 'App Credentials'. It should look like this:
<img src="http://i.imgur.com/or8YuPt.png">
Take note of those values, then navigate to the folder where you cloned the GitHub repo. Just run
<code>CLIENT_ID=xxx.yyy CLIENT_SECRET=abc VERIFICATION_TOKEN=123 PORT=4201 npm start</code>
And then visit <a href="https://foodme.localtunnel.me/login" target="_blank">https://foodme.localtunnel.me/login</a> to install your application.
Remember: you'll need to restart your app using the <pre>npm start</pre> line above each time you make changes to the code.
[We're live! 💪]<9|]
(click: ?9)[### Public or Private?
You can use one of two methods to reply to a slash command: <pre>replyPublic()</pre> or <pre>replyPrivate()</pre>. Public replies show up in the channel for all to see, and private replies are visible only to the user that typed the command. Slack calls those private messages "ephemeral". Usually, help information and personal info is private, while if you want to share something with the group, you can use a public reply.
In our Foodme example, we're going to implement two different actions: one public and one private. Typing <pre>/foodme</pre> will send a public response with your generated food combination, while typing <pre>/foodme help</pre> prints some information about the command privately.
Open up <pre>index.js</pre>. I know it looks like a lot of code, but most of that is there to set up the integration with Slack and Botkit. Scroll down until you see the comment that says <pre>// EDIT ME!</pre>. That's our cue.
[Fire up the food chooser]<10|]
(click: ?10)[### Food, glorious food
As you can see, the template has a list of painstakingly curated food emojis, or as I like to call them, foodmojis 🍔🍜.
Find the comment <pre>// TODO Get three random foods</pre> and replace it with this code that chooses 3 at random from the list:
<code>var food1 = foodmoji`[Math.floor(Math.random() * foodmoji.length)]`;
var food2 = foodmoji`[Math.floor(Math.random() * foodmoji.length)]`;
var food3 = foodmoji`[Math.floor(Math.random() * foodmoji.length)]`;
</code>
Then we can add a line to print out those new choices in fancy emoji form:
<code>slashCommand.replyPublic(message, "How about having " + food1 + " + " + food2 + " + " + food3 + " tonight?");</code>
After you've finished, save the file and restart your app using
<code>CLIENT_ID=xxx.yyy CLIENT_SECRET=abc VERIFICATION_TOKEN=123 PORT=4201 npm start</code>
[Let's test it out!]<11|]
(click: ?11)[### Sample output
By this point, you should have a working slash command! 👏 Go give it a try on your Slack team.
<img src="http://i.imgur.com/uBI9FEQ.png">
[I did it! 🎉]<12|]
(click: ?12)[Whoa, look at you go! You're ready to take on the culinary world by storm now (or at least your rumbling stomach).
This is only the tip of the iceberg on what you can do with the Slack API and slash commands. Maybe you want it to call out to an external service to send you recipes now? Or maybe it should submit an order for those ingredients?
The possibilities are endless, my friend. Always remember, the most powerful gift of all is Imagination.
Magic Rock, signing off. 👋
### Inspiration and Resources
This tutorial was inspired by the <a href="https://medium.com/slack-developer-blog/easy-peasy-slash-commands-getting-started-c37ff3f14d3e#.yreb2w57o" target="_blank">excellent slash commands tutorial</a> by Don Goodman-Wilson. I wanted to show how we can provide learning experiences in an interactive, game-like format.
* <a href="https://api.slack.com/slash-commands" target="_blank">More info on slash commands</a>
* <a href="https://medium.com/slack-developer-blog/slash-commands-style-guide-4e91272aa43a#.w6cks4sk7" target="_blank">Slash commands style guide (highly recommended!)</a>
* <a href="https://api.slack.com" target="_blank">Slack API home page</a>
* <a href="https://howdy.ai/botkit/" target="_blank">Botkit home page</a>
Thanks for reading!
You can contact me with questions, quagmires, or quandaries at alnelson1123@gmail.com or @musegarden on Twitter 💌
Peace! ✌️️
]
blah blah try this code
<code>def do()
dflkdjfs
dklsfjds
dklsjfdsfsd
</code>
also try <pre>/shrug</pre>body
{
background-color: #3EB890;
}
green