Slash Commands Style Guide

How make your slash commands delightful.

We hope you’ve noticed that there is now a super easy way to build slash commands! Slash commands make your users feel powerful. By typing a `/` into the Slack command line, a drop down of possible commands helpfully announce themselves at a user’s fingertips. With a wave of their hand, they can summon an action, like setting a reminder, requesting a Lyft, sharing a riotously amusing gif, or doing any special things that your own custom Slack command can do.

This is amazing!

Of course, if you’re building a nifty slash command, you want it to be easy to use and swiftly understood, and that’s what this style guide is for.

So let’s learn about:

1. Providing friendly slash command usage instructions via `/command help`
2. Using `/command connect` to auth individual users and other granular auth cases
3. Slash command naming conventions
4. When to use public, ephemeral, and delayed responses
5. Slash Commands + Incoming Webhooks = Neat

Help users help themselves with /command help

Whatever your slash command does, you should provide an action called `help`.

If your command is `/please`, you would provide a `/please help` action users can enter on their Slack command line. When invoked, we’ll issue a trigger request to your external URL with the `text` attribute set to `help`. All you need to do is quickly provide a textual ephemeral response explaining to the user how your command works. If your command supported actions like `feed` and `tease`, you would tell the user how to `/please feed` and `/please tease`:

{
   “response_type”: “ephemeral”,
   “text”: “How to use /please”,
   “attachments”:[
       {
          “text”:”To be fed, use `/please feed` to request food. We hear the elf needs food badly.\nTo tease, use `/please tease` — we always knew you liked noogies.\nYou’ve already learned how to get help with `/please help`.”
       }
   ]
}

If your slash command’s actions are sophisticated enough to take arguments, it is wise to also enhance your `help` function to provide illumination on those actions: `/please help feed` and `/please help tease` may explain how you can add a @username to `/please feed @valkyrie` and `/please tease @wizard`.

A slash command that requires actions or arguments to function should provide a default help response. Users inevitably will try using your command without any additional text. If your `/please` command required an argument, then you’d want to offer some version of the `/please help` response when users just type `/please`. This way, users can easily explore your command’s functionality without having to hit the books.

Auth users with /command connect

Some services and applications need to authenticate specific Slack users in a granular way, usually to associate a Slack user with a user account on that service.

It’s cool to do that, but it’s even cooler to follow the “/command connect” convention to handle it. After a user types a command like `/please connect`, you would return an ephemeral message containing a link to a friendly auth flow on your site and follow it up with a fancy landing page with usage instructions. And then you’ll know that “@warrior” on that Slack team is “fancywarrior” in your app and can act accordingly.

To be even more helpful, offer users an opportunity to connect their account the first time they try to utilize a command that requires auth on your service.

The naming of slash commands

Choose a descriptive name for your slash command, but make it easy to recall and type.

If your application provides printing services, then `/print` makes sense, but avoid using copyrighted names that you do not own like `/HP` or `/canon` (unless you work there, and then 🎉). If your service is known by its name, a command with your company’s name in it (like /lyft and /uber to request car sharing service) is an easy way for Slack users to remember how to invoke your slash commands.

You’ll need to balance your careful command naming with knowing that slash commands aren’t namespaced. Be mindful and choose a name that won’t override or be overridden by another developer’s carefully named command.

Pick a name that is simple, easy to remember and connects directly with a purpose. Users shouldn’t have to explore the slash command drop down every time they go to do that thing. Long slash commands can lead to this:

Conventions

Public vs ephemeral responses

By default, the response messages sent to commands will only be visible to the user that issued the command (we call these “ephemeral” messages). However, if you would like the response to be visible to all channel members where the user typed the command, you can add a `response_type` of `in_channel` to the JSON response:

{
   "response_type": "in_channel",
   "text": "It's 80 degrees right now.",
   "attachments": [
      {
         "text":"Partly cloudy today and tomorrow"
      }
   ]
}

Remember that a chatty app is not necessarily a good thing so only pick responses that are important to the entire team for this type of response.

Delayed response

You may notice a `response_url` field included in the initial command request we send you. You can treat them somewhat like Incoming Webhooks, as the response URL is a webhook that allows your app to post additional messages to a channel for a period of time after a command is triggered. Response URLs can be used to send five additional messages within a thirty minute window from the original command invocation.

Any request that you make to the response URL can include either a plain text or JSON-encoded body. If your message is JSON encoded, you may also configure how your message is formatted using markdown. Like Incoming Webhooks, response urls can also include attachments.

Use delayed responses when your action might take more than 3 seconds to perform:

• When humans are involved in the process — approvals, questions and answers services. If the process will take more than 30 min, you may want to consider using a bot user rather than a slash command.
• Long-lasting computation processes — report generation, batch processing, highly distributed processes or even a script that might take more than 3 seconds.
• Retrieving results from external services — if your application relies on remote APIs, you should use delayed responses to mitigate potentially slow response times from 3rd party services.
• Waiting a few seconds to deliver your message, for dramatic effect or to stay on the right beat for workplace comedy.

Though you may be in a hurry to wait and send your delayed response, it’s important to respond to Slack’s initial invocation of your slack command URL with a hardy HTTP 200 OK, just so we know that you’ve received the user’s command.

/Conclusion

Slash commands are a stellar way to invoke your app functionality from within Slack. Following these best practices will make your users working lives simpler, more pleasant and more productive. If you think your slash command is useful for other teams, consider packaging it up as Slack App and submitting it to our directory!