Enabling interactivity with Actions

The rundown
Read this if:You want to share and distribute your app.
Read first:An overview of app interactivity
Read next:Enabling interactivity with Slash Commands

Apps can create custom Actions that allow users to invoke your app in simple, visual ways.

App Actions appear within standard spaces in Slack, such as the message menu, in any workspace where the app is installed.

Once installed, your app's custom actions appear in the More actions section of each Slack message's context menu, beside default actions.

Want to learn more? The only action (pun definitely intended) to take is to read on (and on):

What are App Actions?

Allow your users to quickly invoke specific workflows provided by your Slack app by implementing App Actions.

App Actions can be added to the More actions menu of every non-ephemeral message in Slack workspaces your app is installed in.

When someone uses an App Action in a message's More actions menu, your app will receive context about what happened and where it happened. Use the content of messages to create tasks, send comments to external services, trigger modals, and trigger many more potential workflows.

The potential use cases for App Actions are unbounded.

Here's an example for a hypothetical app called Yogi, with an action that would share a message from a channel to Yogi and create a task on that service:

Actions being used with Dialogs and a confirmation message

You can see how this App Action appears in the More actions menu of a message, how the app triggered a modal for more input, and followed up with a confirmation message.

If you're intrigued, and want to learn more, keep reading...

Setting up App Actions

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 App Actions with your app, there are a few steps you'll need to quickly go through first.

Enabling interactive components

Ensure your app is ready for user interactions by following the preparation steps in our guide to handling user interactions.

Adding the right permissions

To make the actions available in the UI, you need to enable the commands permission scope.

  • From the app 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 may need to be reinstalled before actions may be used, and if your app is published in the App Directory, the changes will be reflected only after the app is reviewed and approved.

Creating an App Action

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

  • Open your app's management dashboard
  • Click on Interactive Components in the sidebar
  • Click on the Create New Action button under Actions and fill in the following:
    • Action Name: a short, catchy call to action. If your action will trigger a modal, we recommend including an ellipsis (...) at the end of the action name as an establish UI pattern to indicate a follow-up decision will occur.
    • Short Description: describe what the action 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.

Create new Action Dialog

  • Click that tempting green Create button, and you'll be sent back to the Interactive Components page.

  • On that page you'll either need to click the Save Changes button, or if you're just setting up interactive components for the first time, you'll need to click the Enable Interactive Components button (yes, you've already clicked one of those before, but you'll need to do it again at this point).

That's it! You've created your first App Action (and you can create 4 more - each app can have up to 5 App Actions for messages) and are ready to receive interaction payloads and do something in response.

Handling actions in your app

You've created an app action, and at some point it will be used by someone in Slack. Your app has to handle that eventuality, so here's what will happen:

  1. An HTTP POST request will be sent to your app's Request URL.
  2. Your app will process the payload contained in that request.
  3. Your app will do something in response.

The first step is handled by Slack, so let's run through the other two.

Processing the interaction payload

When an action 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.

After you've parsed it, you'll see an interaction payload — consult our reference guide to see the exact structure of the fields included.

You'll notice that the payload contains plenty of information that can be used to ascertain the context of the interaction.

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 actions

As soon as your app receives the request sent by an action a countdown begins, because this message will self-destruct in 3 seconds.

In other words, if your app doesn't respond with an HTTP status 200 OK within 3000ms of receiving the request, the user who clicked to initiate the action will receive the following error message:

Actions timeout error message

This is what we call an acknowledgment response — read more about these in our guide to handling user interactions.

But that's not the only way your app can respond.

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