Creating and handling shortcuts

Shortcuts give Slack users clear entry points to access your app.

There are a few short steps to creating shortcuts, letting you focus on perfecting your potential response.

Don't take any shortcuts here (pun definitely intended). Read on to learn more.

• What's the difference between message and global shortcuts?
• Getting started with message shortcuts
  • Enabling interactive components
  • Creating a custom action
  • Adding the right permissions
• Handling shortcuts usage
  • Processing the interaction payload
  • Responding to shortcuts
  • Sending messages in response to global shortcuts
• Limitations
• Known issues
• Coming soon

---

What's the difference between message and global shortcuts?

Shortcuts are a type of element in Slack clients that invoke a helpful action. Apps can create their own shortcuts and use them as a trigger for interactive workflows.

When someone uses one of your shortcuts, your app will receive some context about what happened in an interaction payload.

There are two different types of shortcut that apps can create. Let's take a look at them in more detail.

Global Shortcuts

Global shortcuts are ever-present companions in a user's life in Slack.

They can be initiated from the shortcuts button in the message composer, or from within search.

These type of shortcuts are intended to trigger workflows that can operate without the context of a channel or message.

For example, users might trigger a global shortcut to create a calendar event or view their upcoming on-call shifts.

Message Shortcuts

Message shortcuts allow users to invoke your app from the comfort of the humble Slack message.

They are shown in the context menu of any non-ephemeral message.

Message shortcuts will retain the context of the source message from which they were initiated. This makes them ideal when you have a workflow that relies on that context to work.

For example, users might quickly generate tasks from a posted message, or send messages to external services.

---

Getting started with shortcuts for apps

If you don't have a Slack app yet, what are you waiting for? Follow our quick guide to create one.

In order to start using shortcuts with your app, there are a few preparation steps you'll need to go through.

Preparing for payloads

Ensure your app is ready to receive interaction payloads by providing a Request URL, as described in our guide to handling user interactions.

Adding the right permissions

To make shortcuts available in Slack, your app must have the commands permission scope. You can either request this scope during the OAuth flow or add it to your app OAuth settings:

• From your app's dashboard, click the menu item OAuth & Permissions.

• Under Scopes, type commands into the text field, select the correct permission to add it, then click Save Changes.

If your app isn't already requesting commands at installation, it will need to be reinstalled before shortcuts can be used. If your app is published in the App Directory, the changes will be reflected only after the app is reviewed and approved.

Creating a shortcut

Now that your app is ready, it's time to create some potential interaction energy:

• Open your app's dashboard

• Click on Interactivity & Shortcuts in the sidebar

• Click the Create New Shortcut button under Shortcuts

• Select from the Global and On messages options, depending on which type of shortcut you want and click Next

• Fill in the following:

  • Name: a short, catchy call to action. Start the name with a verb, and use sentence case (eg. “Create a ticket”).
  • Short Description: describe what the shortcut does for the benefit of a potential user.
  • Callback ID: a string that will be sent to your Request URL in an interaction payload — we'll talk about this more later on.

• Click that tempting green Create button, and you'll be sent back to the Interactivity & Shortcuts page.

• On that page you'll need to click the Save Changes button.

That's it—you've created your first shortcut! You can create some more—each app can have up to 5 global shortcuts, and separately, 5 message shortcuts. Shortcuts will appear in shortcuts menus in the order in which they were created.

Now let's make sure you are ready to receive interaction payloads and do something in response.

---

Handling the use of shortcuts in your app

You've created a shortcut, and at some point it will be used by someone in Slack. Your app has to handle that eventuality.

We explain the process in-depth in our guide to handling user interactions in apps, including how to prepare your app with a request URL.

In short, your app will receive an interaction payload after someone uses one of your shortcuts. Your app must process that payload and then send a response.

First, let's learn more about that interaction payload.

Processing the interaction payload

When a shortcut is invoked, a request will be sent to the app's configured Request URL. The request body will contain a payload parameter that your app should parse for JSON.

Inside you'll discover an interaction payload containing lots of useful context — consult our reference guide to see the full structure of the fields included.

Payloads for global shortcuts will contain different info from payloads for message shortcuts. For example, a payload for a message shortcut will include channel and message context, and a response_url for publishing message responses. If you want to publish a message in response to a global shortcut, use our alternative approach.

Now you've parsed the payload basketball that Slack passed to you, it's time to start figuring out your next move so you finish with a slam dunk.

Responding to shortcuts

There are a few things to consider about responding to interaction payloads:

1. Always send an acknowledgment response.

   As soon as your app receives the interaction payload, a countdown begins, because this message will self-destruct in 3 seconds. If your app doesn't respond with an HTTP status 200 OK within 3000ms of receiving the payload, the person who used the shortcut will see a generic error message letting them know that something went wrong.

2. Your app must follow up with a modal to confirm any action that will occur.

   This will allow the user to feel much more confident using any shortcut, as they can trust that they won't immediately publish a message or modify data.

3. Beyond these essential actions, your app also has a range of more complex responses to take.

   You can use a field supplied in the interaction payload to publish messages, or another payload field to pop a modal that can collect or present more info. Shortcuts can also be a trigger for your app to make calls to APIs or external services.

A note about global shortcuts and sending messages
If you're using global shortcuts, and want to publish messages as a response, you can do so by triggering a modal containing a special conversation selector.

Read our guide to using this technique.

Apps should use this approach to ensure that users know that they can use any shortcut without an unexpected message being published on their behalf.

---

Next steps

You've now learned how to create a shortcut, and what your app has to do to handle their use. That's a great start!

Read our guide to responding to interactions to understand the vast range of possibilities open to your app at this point.

---

Limitations

Global shortcuts are not visible (and therefore usable) for all types of guest user. Please see our Help Center for an up-to-date breakdown of the availability of shortcuts for these users.

---

Known issues

• When an app is submitted (or re-submitted) to the App Directory, the confirmation modal does not indicate any changes regarding global shortcuts. Despite the discrepancy, global shortcut changes will be submitted upon confirmation.

---

Coming soon

• An app responding to a shortcut initiated from a threaded message cannot currently publish a message back to that thread. They can publish back to the parent conversation. We are working on a comprehensive solution that will make this possible.