Respond to quick commands as a Google Chat app

This page explains how to set up and respond to quick commands for your Google Chat app.

A quick command is a way that users can invoke and interact with a Chat app. To use a quick command, open the integration menu by clicking Google Workspace Tools in a Chat space or conversation, and then select an app command with a name that does not begin with a slash (/). By selecting a quick command, the Chat app is directly invoked without further inputs from the user, allowing for fast user interactions.

Users can also invoke a Chat app through a slash command. For steps, see Respond to slash commands. In comparison to slash commands, quick commands are formatted with a more user-friendly name in the Chat UI, they are invoked immediately upon selection, and they don't require the user to remember or type out the name of the slash command.

Integration menu with quick commands
Figure 1: The integration menu containing quick commands for a Chat app.

Set up a quick command in the Google Chat API

To create a quick command or update any existing slash commands to quick commands, you must specify information about the command in your Chat app's configuration for the Google Chat API.

To configure a quick command in the Google Chat API, complete the following steps:

  1. In the Google Cloud console, click Menu > APIs & Services > Enabled APIs & Services > Google Chat API

    Go to the Google Chat API page

  2. Click Configuration.

  3. Under Commands, click Add a command.

  4. Enter a command ID, name, description, and command type for the command:

    • Command ID: a number from 1 to 1000 that your Chat app uses to recognize the command and return a response.
    • Name: the display name for the command. Names can be up to 50 characters and can include special characters.
      • Use short, descriptive, and actionable words or phrases to make the commands clear to the user. For example, use Update contact for a command that modifies a contact record.
    • Description: the text that describes what the command does. Descriptions can be up to 50 characters and can include special characters.
      • Keep the description short and clear so that users know what to expect when they invoke the command.
      • Let users know if the Chat app replies to everyone in the space, or privately to the user who invokes the command. For example, for the quick command About, you could describe it as Learn about this app (Only visible to you).
    • Command type: select Quick command.

  5. Optional: If you want your Chat app to respond to the command with a dialog, select the Open a dialog checkbox.

  6. Click Save.

The quick command is now configured for the Chat app.

Respond to a quick command

When users invoke a quick command, your Chat app receives an APP_COMMAND interaction event. The event payload contains the appCommandMetadata object with details about the command that was invoked (including the command ID and the command type), so that you can return an appropriate response.

The following code shows an example of a Chat app that replies to the Help command by handling APP_COMMAND interaction events and detecting whether the event payload contains the matching command ID. If the event payload contains the command ID, the Chat app returns a private message:

Apps Script 

// Handle the APP_COMMAND event type.
function onAppCommand(event) {
  // Executes the command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Set HELP_COMMAND_ID with the command ID that you specified when you configured the quick command in the Chat API. To test this code, see Test interactive features for Google Chat apps. To test a quick command in Chat, open the integration menu by clicking Google Workspace Tools and then selecting your quick command.

Turn existing slash commands to quick commands

To modify an existing slash command into a quick command, edit the slash command in the Google Chat API by changing the Command type from Slash command to Quick command.

When users invoke a quick command, your Chat app receives an APP_COMMAND interaction event, instead of a MESSAGE interaction event that is sent for slash commands. Update your Chat app to handle this interaction event type by reading the event payload containing the appCommandMetadata object with details about the quick command that was invoked. See Respond to a quick command.