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

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

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

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

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

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

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

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

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

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

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

Node.js

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

Скрипт приложений

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

Питон

Ява

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

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

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

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

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

Название и описание команды слэш — **Рисунок 3.** Имя и описание косой черты.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Node.js

узел/аватар-приложение/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.'
      });
  }
}

Скрипт приложений

приложения-скрипт/аватар-приложение/аватар-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/аватар-приложение/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/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

узел/аватар-приложение/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.'
      });
  }
}

Скрипт приложений

приложения-скрипт/аватар-приложение/аватар-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/аватар-приложение/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/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.

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

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

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

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

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

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

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

Node.js

Скрипт приложений

Питон

Ява

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

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

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

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

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

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

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

Node.js

Скрипт приложений

Питон

Ява

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

Node.js

Скрипт приложений

Питон

Ява

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

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