Отвечать на команды приложения 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, выполните следующие действия: Чтобы настроить слэш-команду в API Google Chat, выполните следующие действия:

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

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

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

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

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

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

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

// 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.'
      };
  }
}

# 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 {}

// 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;
  }
}

// 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 .

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

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

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

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

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