Отвечать на команды приложения Google Chat

This page explains how to set up and respond to commands as a Google Chat app.

Команды помогают пользователям находить и использовать ключевые функции приложения для чата. Содержимое команды видят только приложения для чата. Например, если пользователь отправляет сообщение с командой, содержащей косую черту, сообщение будет видно только пользователю и приложению для чата.

To decide whether you should build commands, and to understand how to design user interactions, see Define all user journeys .

Types of Chat app commands

1. Команды со слэшем: Пользователи могут выбрать команду со слэшем из меню или ввести слэш ( / ) и затем предопределенный текст, например /about . В чат-приложениях обычно требуется текстовый аргумент для команды со слэшем.

   Если ваше приложение для чата требует от пользователя дополнительного ввода, создайте команду со слэшем. Например, вы можете создать команду со слэшем под названием /search , которая будет выполняться после того, как пользователь введет поисковую фразу, например, /search receipts .

2. Quick commands: Users use commands by opening the menu from the reply area of a Chat message. To use a command, they click Add and select a command from the menu.

   Создайте быструю команду, если ваше приложение для чата может отвечать пользователю немедленно, без ожидания дополнительного ввода. Например, вы можете создать быструю команду под названием «Случайное изображение» , которая немедленно отправит пользователю изображение.

3. Действия с сообщениями: ( science предварительная версия для разработчиков) Пользователи используют действия с сообщениями, наводя курсор на сообщение и щелкая по меню с тремя точками. Чтобы использовать команду, они открывают меню с тремя точками и выбирают команду из меню.

   Если ваше приложение для чата может выполнять действия на основе контекста сообщения, создайте действие для сообщения.

The following images show how users discover the menu for slash and quick commands, and message actions:

Предварительные требования

Set up the command

This section explains how to complete the following steps to set up the command:

1. Create a name and description for the command.
2. Настройте команду в консоли Google Cloud.

Name and describe the command

Название команды — это то, что пользователи вводят или выбирают для вызова приложения «Чат». Ниже названия также отображается краткое описание, чтобы подсказать пользователям, как использовать команду:

При выборе названия и описания для вашего подразделения учитывайте следующие рекомендации:

To name a command:

• Используйте короткие, описательные и действенные слова или фразы, чтобы команды были понятны пользователю. Например, вместо названия Create a reminder » используйте Remind me .
• Рассмотрите возможность использования уникального или общеупотребительного имени для вашей команды. Если ваша команда описывает типичное взаимодействие или функцию, вы можете использовать общеупотребительное имя, которое пользователи узнают и ожидают, например, Settings или Feedback . В противном случае, старайтесь использовать уникальные имена команд, потому что если имя вашей команды одинаково в других приложениях для чата, пользователю придется просматривать похожие команды, чтобы найти и использовать вашу.

To describe a command:

• Keep the description short and clear so that users know what to expect when they use the command.
• Сообщите пользователям, если для команды существуют какие-либо требования к форматированию. Например, если вы создаете команду со слэшем, требующую текстового аргумента, установите описание примерно такого вида: Remind me to do [something] at [time] .
• Сообщите пользователям, отвечает ли приложение чата всем участникам в пространстве или только тому пользователю, который вызвал команду. Например, для быстрой команды About » можно описать её как Learn about this app (Only visible to you) .

Configure the command in the Google Cloud console

Для создания команды с косой чертой, быстрой команды или действия с сообщением необходимо указать информацию о команде или действии в конфигурации вашего приложения чата для API Google Chat.

Для настройки команды в API Google Chat выполните следующие шаги:

1. В консоли Google Cloud перейдите в menu «Меню» > «API и сервисы» > «Включенные API и сервисы» > «Google Chat API».

   Go to the Google Chat API page

2. Click Configuration .

3. Under Commands , click Add a command .

4. Введите идентификатор команды, описание, тип команды и имя команды:

   • Идентификатор команды: число от 1 до 1000, которое ваше приложение чата использует для распознавания команды и возврата ответа.
   • Описание: текст, описывающий действие команды. Описание может содержать до 50 символов и включать специальные символы.
   • Тип команды: выберите либо «Быстрая команда» , «Команда со слэшем» , либо «Действие сообщения» .
   • Specify a name for the command:
     • Название быстрой команды: отображаемое имя, которое пользователи выбирают из меню для вызова команды. Может содержать до 50 символов и включать специальные символы. Например, Remind me .
     • Название команды с косой чертой: текст, который пользователи вводят для вызова команды в сообщении. Должен начинаться с косой черты, содержать только текст и может содержать до 50 символов. Например, /remindMe .
     • Название действия сообщения: ( science предварительная версия для разработчиков) Отображаемое имя, которое пользователи выбирают из меню для вызова действия сообщения. Может содержать до 50 символов и включать специальные символы. Например, Remind me .

5. Необязательно: Уведомление о загрузке : ( science Developer Preview) Всплывающее уведомление, отображаемое пользователю во время выполнения действия с сообщением. Доступно только для действий с сообщениями, которые не открывают диалоговые окна.

6. Необязательно: если вы хотите, чтобы ваше приложение чата ответило на команду диалоговым окном , установите флажок «Открыть диалоговое окно».

7. Нажмите « Сохранить ».

The command is now configured for the Chat app.

Respond to a command

Когда пользователи используют команду, ваше приложение «Чат» получает событие взаимодействия . Полезная нагрузка события содержит метаданные с подробной информацией о вызванной команде (включая идентификатор команды и тип команды), чтобы вы могли вернуть соответствующий ответ.

Для реагирования на каждый тип команды необходимо обрабатывать различные типы событий и объекты метаданных в полезной нагрузке события:

Чтобы узнать, как ответить на команду сообщением, см. следующие разделы.

Respond to a slash command

Приведенный ниже код демонстрирует пример чат-приложения, отвечающего на команду /about . Чат-приложение обрабатывает события взаимодействия MESSAGE , определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает личное сообщение:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Замените ABOUT_COMMAND_ID на идентификатор команды, который вы указали при настройке команды в консоли Google Cloud.

Respond to a quick command

Приведенный ниже код демонстрирует пример приложения чата, которое отвечает на быструю команду « Помощь» . Приложение чата обрабатывает события взаимодействия APP_COMMAND , определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает личное сообщение:

/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick 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.'
      };
  }
}

def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}

/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Замените HELP_COMMAND_ID на идентификатор команды, который вы указали при настройке команды в консоли Google Cloud.

Respond to a message action

Приведенный ниже код демонстрирует пример чат-приложения, отвечающего на сообщение «Напомнить мне» . Чат-приложение обрабатывает события взаимодействия APP_COMMAND , определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает личное сообщение:

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function handleAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  // Use appCommandType to detect message actions.
  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return res.send({
      text: `Setting a reminder for this message: "${messageText}"`
    });
  }
}

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.message.text;

    // Return a response that includes details from the original message.
    return { "text": "Setting a reminder for message: " + messageText };
  }
}

def handle_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    metadata = event.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = event.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "text": f'Setting a reminder for message: "{message_text}"'
        }

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject metadata = event.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = event.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);
      response.getWriter().write(responseMessage.toString());
    }
  }
}

Замените REMIND_ME_COMMAND_ID на идентификатор команды, который вы указали при настройке команды в консоли Google Cloud.

Test the command

Чтобы проверить команду и код, см. раздел «Тестирование интерактивных функций для приложений Google Chat» .

Чтобы узнать, как протестировать и использовать эту команду в пользовательском интерфейсе чата, см. раздел «Использование приложений в Google Chat» в справочной документации Google Chat.

Связанные темы

• View Chat app samples that use commands
• Отправить сообщение
• Open interactive dialogs