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

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

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

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

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

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

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

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

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

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

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

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

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

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

HTTP

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

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

Apps Script

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

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

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

1. Придумайте название и описание для команды.
2. Настройте команду в консоли 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 выполните следующие шаги:

1. В консоли Google Cloud перейдите в «Меню» > «API и сервисы» > «Включенные 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, которое ваше приложение чата использует для распознавания команды и возврата ответа.
   2. Описание: текст, описывающий, как использовать и форматировать команду. Описание может содержать до 50 символов.
   3. Тип команды: выберите либо быструю команду , либо команду с косой чертой .
   4. Укажите имя для команды быстрого выполнения или команды с косой чертой:
      • Название быстрой команды: отображаемое имя, которое пользователи выбирают из меню для вызова команды. Может содержать до 50 символов и включать специальные символы. Например, Remind me .
      • Название команды с косой чертой: текст, который пользователи вводят для вызова команды в сообщении. Должен начинаться с косой черты, содержать только текст и может содержать до 50 символов. Например, /remindMe .

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

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

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

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

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

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

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

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

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

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

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

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