Эта страница переведена с помощью Cloud Translation API.

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

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

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

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

Типы команд приложения «Чат»

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

Команды со слэшем: Пользователи могут выбрать команду со слэшем из меню или ввести слэш ( / ) и затем предопределенный текст, например /about . В чат-приложениях обычно требуется текстовый аргумент для команды со слэшем.
Если ваше приложение для чата требует от пользователя дополнительного ввода, создайте команду со слэшем. Например, вы можете создать команду со слэшем под названием /search , которая будет выполняться после того, как пользователь введет поисковую фразу, например, /search receipts .
Быстрые команды: Пользователи используют команды, открывая меню из области ответа на сообщение в чате. Чтобы использовать команду, они нажимают кнопку «Добавить». и выберите команду из меню.
Создайте быструю команду, если ваше приложение для чата может отвечать пользователю немедленно, без ожидания дополнительного ввода. Например, вы можете создать быструю команду под названием «Случайное изображение» , которая немедленно отправит пользователю изображение.
Действия с сообщениями: ( предварительная версия для разработчиков) Пользователи используют действия с сообщениями, наводя курсор на сообщение и щелкая по меню с тремя точками. Чтобы использовать команду, они открывают меню с тремя точками и выбирают команду из меню.
Если ваше приложение для чата может выполнять действия на основе контекста сообщения, создайте действие для сообщения.

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

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

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

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

Node.js

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

Apps Script

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

Python

Java

Настройте команду

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

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

Назовите и опишите команду.

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

Название и описание команды слэша — Название и описание команды, использующей косую черту.

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

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

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

Для описания команды:

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

Настройте команду в консоли Google Cloud.

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

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

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

Теперь эта команда настроена для приложения «Чат».

Отреагировать на команду

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

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

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

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

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

Ответить на команду с косой чертой

Приведенный ниже код демонстрирует пример чат-приложения, отвечающего на команду /about . Чат-приложение обрабатывает события взаимодействия 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.

Отреагируйте на быструю команду

Приведенный ниже код демонстрирует пример приложения чата, которое отвечает на быструю команду « Помощь» . Приложение чата обрабатывает события взаимодействия 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.

Ответить на действие, указанное в сообщении

Приведенный ниже код демонстрирует пример чат-приложения, отвечающего на сообщение «Напомнить мне» . Чат-приложение обрабатывает события взаимодействия 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» .

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

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

Отвечать на команды приложения Google 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