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

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

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

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

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

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

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

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

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

Предпосылки

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

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

1. Создайте имя и описание для команды.
2. Настройте команду в консоли 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 для API Google Chat.

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

1. В консоли Google Cloud выберите menu > API и службы > Включенные API и службы > API Google Chat.

   Перейти на страницу API Google Chat

2. Нажмите Конфигурация .

3. В разделе «Команды» нажмите «Добавить команду» .

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

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

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

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

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

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

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

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

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

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

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

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

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

Проверьте команду

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

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

Похожие темы

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