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

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

Примечание. В Google Chat дополнения показываются пользователям как приложения Google Chat. Вы также можете создать приложение Chat, используя события взаимодействия с Google Chat API. Подробнее о расширении возможностей Google Chat…

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования

HTTP

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

Примечание. Примеры кода в этом руководстве написаны для запуска в качестве функции Google Cloud Run для Node.js.

Apps Script

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

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

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

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 для Google Chat API.

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

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

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

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

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

   1. URL конечной точки HTTP. Здесь можно указать один общий URL конечной точки HTTP. Чтобы использовать разные конечные точки HTTP для разных триггеров, укажите конечную точку непосредственно в поле Команда приложения.
   2. Apps Script. Введите идентификатор развертывания Apps Script. По умолчанию будет вызвана функция onAppCommand. Чтобы использовать другую функцию Apps Script, укажите ее название в поле Команда приложения.

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

5. Укажите следующую информацию о команде:

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

6. Необязательно: Сообщение уведомления о загрузке – всплывающее уведомление, которое показывается пользователю во время выполнения действия с сообщением. Доступно только для действий с сообщениями, которые не открывают диалоговые окна.

7. Если вы хотите, чтобы приложение Chat отвечало на команду с помощью диалогового окна, установите флажок Открыть диалоговое окно.

8. Нажмите Сохранить.

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

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

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

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

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

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

Примечание. Если команда сопоставлена с активным вариантом запроса, вы не сможете удалить ее или изменить ее тип в таблице Команды, пока не удалите сопоставление в разделе Варианты запросов.

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

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

Приложение Chat отвечает на слеш-команду /help, объясняя, как получить поддержку.

В приведенном ниже коде показан пример приложения Chat, которое отвечает на слеш-команду /about текстовым сообщением. Чтобы отвечать на команды со слешем, приложение Chat обрабатывает объекты событий из триггера Команда приложения. Если полезная нагрузка объекта события содержит идентификатор команды со слешем, приложение Chat возвращает действие DataActions с объектом createMessageAction:

Node.js

node/chat/avatar-app/index.js

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

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/chat/avatar-app/main.py

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

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

Java

java/chat/avatar-app/src/main/java/com/google/chat/avatar/App.java

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

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

Apps Script

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

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

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'The Avatar app replies to Google Chat messages.'
      }}}}};
  }
}

Чтобы использовать этот пример кода, замените ABOUT_COMMAND_ID на идентификатор команды, который вы указали при настройке команды в Chat API.

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

В приведенном ниже коде показан пример приложения Chat, которое отвечает на действие с сообщением Напомни мне текстовым сообщением. Чтобы отвечать на действия с сообщениями, приложение Chat обрабатывает объекты событий из триггера команды приложения. Если полезная нагрузка объекта события содержит идентификатор команды действия с сообщением, приложение Chat возвращает действие DataActions с объектом createMessageAction:

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 onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

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

Python

def on_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.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.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 = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "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 onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.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 = payload.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);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

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.chat.appCommandPayload.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.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

Чтобы использовать этот пример кода, замените REMIND_ME_COMMAND_ID на идентификатор команды, который вы указали при настройке команды в Chat API.

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

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

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

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

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