Чтобы переводить контент на ваш предпочитаемый язык, Google использует технологии на основе искусственного интеллекта. Переводы от ИИ могут содержать ошибки.

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

На этой странице рассказывается, как настроить приложение Google Chat для работы с командами и отвечать на них.

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

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

Типы команд приложений Chat

Команды приложений Chat можно создавать в виде слеш-команд, быстрых команд или действий с сообщениями. Чтобы использовать каждый тип команды, пользователи могут выполнить следующие действия:

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

Создайте команду со слешем, если приложению Chat требуется дополнительный ввод от пользователя. Например, можно создать слеш-команду /search, которая будет выполняться после того, как пользователь введет фразу для поиска, например /search receipts.
Быстрые команды. Пользователи могут использовать команды, открывая меню в области ответа на сообщение Chat. Чтобы использовать команду, нажмите Добавить и выберите команду в меню.

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

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

На изображениях ниже показано, как пользователи могут найти меню для слеш-команд, быстрых команд и действий с сообщениями:

Пользователь открывает меню слеш-команд и быстрых команд. — Пользователи видят меню слеш-команд и быстрых команд.

Пользователь обнаруживает контекстное меню сообщения, содержащее действие с сообщением. — Пользователи видят контекстное меню сообщения, содержащее действие с сообщением "Напомнить мне".

Требования

Node.js

Приложение Google Chat, которое получает события взаимодействия и реагирует на них. Чтобы создать интерактивное приложение Chat с помощью HTTP-сервиса, выполните краткое руководство.

Apps Script

Приложение Google Chat, которое получает события взаимодействия и реагирует на них. Чтобы создать интерактивное приложение Chat в Apps Script, выполните инструкции по быстрому началу работы.

Python

Java

Как настроить команду

В этом разделе рассказывается, как выполнить следующие действия, чтобы настроить команду:

Укажите название и описание команды.
Настройте команду в консоли Google Cloud.

Введите название и описание команды

Название команды – это то, что пользователи вводят или выбирают, чтобы вызвать приложение Chat. Под названием также показывается краткое описание, которое помогает пользователям понять, как использовать команду:

При выборе названия и описания команды следуйте приведенным ниже рекомендациям.

Чтобы задать название команды:

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

Чтобы описать команду:

Описание должно быть кратким и понятным, чтобы пользователи знали, чего ожидать при использовании команды.
Сообщайте пользователям, если для команды есть требования к форматированию. Например, если вы создаете команду со слешем, для которой требуется текст аргумента, укажите в описании что-то вроде Remind me to do [something] at [time].
Сообщите пользователям, отвечает ли приложение Chat всем участникам чат-группы или только тому, кто вызвал команду. Например, для быстрой команды About можно указать описание Learn about this app (Only visible to you).

Как настроить команду в консоли Google Cloud

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

Чтобы настроить команду в Google Chat API, выполните следующие действия:

В консоли Google Cloud нажмите на значок меню > APIs & Services (API и сервисы) > Enabled APIs & Services (Включенные API и сервисы) > Google Chat API.

Перейти на страницу Google Chat API
Нажмите Конфигурация.
В разделе Команды нажмите Добавить команду.
Введите идентификатор команды, описание, тип команды и название команды:
- Идентификатор команды – число от 1 до 1000, которое приложение Chat использует для распознавания команды и возврата ответа.
- Описание. Текст, описывающий, что делает команда. Описания могут содержать до 50 символов, в том числе специальных.
- Тип команды. Выберите Быстрая команда, слеш-команда или Действие с сообщением.
- Укажите название команды:
  - Название быстрой команды. Отображаемое название, которое пользователи выбирают в меню, чтобы вызвать команду. Может содержать до 50 символов, включая специальные. Пример: Remind me.
  - Название слеш-команды. Текст, который пользователи вводят, чтобы вызвать команду в сообщении. Должен начинаться с косой черты, содержать только текст и иметь длину не более 50 символов. Пример: /remindMe.
  - Название действия с сообщением. Отображаемое название, которое пользователи выбирают в меню, чтобы вызвать действие с сообщением. Может содержать до 50 символов, включая специальные. Пример: Remind me.
Необязательно: Сообщение уведомления о загрузке – всплывающее уведомление, которое показывается пользователю во время выполнения действия с сообщением. Доступно только для действий с сообщениями, которые не открывают диалоговые окна.
Если вы хотите, чтобы приложение Chat отвечало на команду с помощью диалогового окна, установите флажок Открыть диалоговое окно.
Нажмите Сохранить.

Команда настроена для приложения Chat.

Сопоставление команд с запросами для начала работы

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

Чтобы сопоставить команду с вариантом запроса:

Убедитесь, что для команды не требуются дополнительные аргументы (в качестве начальных запросов поддерживаются только команды с Нет аргументов или Основные аргументы).
В консоли Google Cloud перейдите на страницу Configuration (Конфигурация) Chat API.
В разделе Интерактивные функции > Подсказки для начала нажмите Добавить подсказку.
Установите ранг (1–3) для порядка показа.
В разделе Выбор типа выберите Командная строка и укажите команду в раскрывающемся списке.
Нажмите кнопку Готово, а затем – Сохранить.

Как отвечать на команды

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

Личное сообщение для приложения Cymbal Labs Chat. В сообщении говорится, что приложение Chat создано Cymbal Labs, и приведены ссылки на документацию и службу поддержки. — Приложение Chat отвечает на слеш-команду `/help`, объясняя, как получить поддержку.

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

Тип команды	Тип события	Метаданные команды
Слеш-команда	`MESSAGE`	`message.slashCommand` или `message.annotation.slashCommand`
Быстрая команда	`APP_COMMAND`	`appCommandMetadata`
Действие с сообщением	`APP_COMMAND`	`appCommandMetadata`

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

Как ответить на слеш-команду

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

Node.js

node/avatar-app/index.js

Посмотреть на GitHub

/**
 * 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.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Посмотреть на GitHub

// 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.'
      };
  }
}

Python

python/avatar-app/main.py

Посмотреть на GitHub

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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Посмотреть на GitHub

/**
 * 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.

Отвечать на быстрые команды.

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

Node.js

node/avatar-app/index.js

Посмотреть на GitHub

/**
 * 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.'
      });
  }
}

Apps Script

apps-script/avatar-app/avatar-app.gs

Посмотреть на GitHub

/**
 * 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.'
      };
  }
}

Python

python/avatar-app/main.py

Посмотреть на GitHub

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 {}

Java

java/avatar-app/src/main/java/AvatarApp.java

Посмотреть на GitHub

/**
 * 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.

Как ответить на действие с сообщением

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

Node.js

/**
 * 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}"`
    });
  }
}

Apps Script

/**
 * 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 };
  }
}

Python

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}"'
        }

Java

/**
 * 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.

Как проверить команду

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

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

Примеры приложений Chat, использующих команды
Как отправить сообщение
Как открыть интерактивные диалоговые окна

Как отвечать на команды приложений Google Chat Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Типы команд приложений Chat

Требования

Node.js

Apps Script

Python

Java

Как настроить команду

Введите название и описание команды

Чтобы задать название команды:

Чтобы описать команду:

Как настроить команду в консоли Google Cloud

Сопоставление команд с запросами для начала работы

Как отвечать на команды

Как ответить на слеш-команду

Node.js

Apps Script

Python

Java

Отвечать на быстрые команды.

Node.js

Apps Script

Python

Java

Как ответить на действие с сообщением

Node.js

Apps Script

Python

Java

Как проверить команду

Статьи по теме

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