На этой странице рассказывается, как настроить команды и ответы на них в приложении Google Chat.
Команды помогают пользователям находить и использовать основные функции приложения Chat. Только приложения Chat могут видеть содержимое команды. Например, если пользователь отправляет сообщение со слеш-командой, оно видно только ему и приложению Chat.
Чтобы решить, нужно ли создавать команды, и понять, как проектировать взаимодействие с пользователем, ознакомьтесь с разделом Определите все пути пользователя.
Типы команд приложений Chat
Команды приложения Chat можно создавать как слеш-команды, быстрые команды или действия с сообщениями. Чтобы использовать каждый тип команд, пользователи могут сделать следующее:-
Слеш-команды. Пользователи могут выбрать слеш-команду в меню или ввести слеш (
/), а затем заданный текст, например/about. Обычно для слеш-команд в приложениях Chat требуется текст аргумента.Создайте слеш-команду, если вашему приложению Chat требуются дополнительные входные данные от пользователя. Например, вы можете создать слеш-команду
/search, которая будет выполняться после того, как пользователь введет поисковый запрос, например/search receipts. -
Быстрые команды. Пользователи могут выбирать команды из меню в области ответа в сообщении Chat. Чтобы использовать команду, нужно нажать Добавить
и выбрать команду в меню.
Создайте быструю команду, если приложение Chat может ответить пользователю сразу, не дожидаясь дополнительных данных. Например, вы можете создать быструю команду Случайное изображение, которая будет сразу отправлять изображение.
-
Действия с сообщениями. Чтобы выполнить действие с сообщением, пользователь наводит на него указатель мыши и нажимает на значок меню в виде трех точек. Чтобы использовать команду, нужно открыть меню в виде трех точек и выбрать команду из меню.
Создайте действие с сообщением, если ваше приложение Chat может выполнять действия на основе контекста сообщения.
На изображениях ниже показано, как пользователи находят меню слеш-команд, быстрых команд и действий с сообщениями.
Требования
HTTP
Приложение Google Chat, которое получает взаимодействия с пользователями и отвечает на них. Чтобы создать его, выполните инструкции из краткого руководства по HTTP.
Apps Script
Приложение Google Chat, которое получает взаимодействия с пользователями и отвечает на них. Чтобы создать его, ознакомьтесь с кратким руководством по Apps Script.
Настройте команду
В этом разделе объясняется, как выполнить следующие шаги для настройки команды:
- Укажите название и описание команды.
- Настройте команду в консоли 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, выполните следующие действия:
В консоли Google Cloud нажмите на значок меню > APIs & Services (API и сервисы) > Enabled APIs & Services (Включенные API и сервисы) > Google Chat API
Нажмите Конфигурация.
В разделе Настройки подключения перейдите к пункту Триггеры и укажите сведения о конечной точке. Вы должны использовать этот триггер в следующем разделе, чтобы ответить на команду.
- URL конечной точки HTTP. Здесь можно указать один общий URL конечной точки HTTP. Если вы хотите использовать разные конечные точки HTTP для разных триггеров, укажите конечную точку непосредственно в поле Команда приложения.
- Apps Script. Введите идентификатор развертывания Apps Script. По умолчанию будет вызываться функция
onAppCommand. Чтобы использовать другую функцию Apps Script, укажите ее название в поле Команда приложения.
В разделе Команды нажмите Добавить команду.
Укажите следующую информацию о команде:
- Идентификатор команды. Число от 1 до 1000, которое приложение Chat использует для распознавания команды и возврата ответа.
- Описание. Текст, описывающий, как использовать и форматировать команду. а описания – до 50.
- Тип команды. Выберите Быстрая команда, Слеш-команда или Действие с сообщением.
- Укажите название команды:
- Название быстрой команды. Отображаемое название, которое пользователи выбирают в меню, чтобы вызвать команду. Может содержать до 50 символов, включая специальные. Пример:
Remind me. - Название слеш-команды. Текст, который пользователи вводят, чтобы вызвать команду в сообщении. Должен начинаться с косой черты, содержать только текст и не превышать 50 символов. Пример:
/remindMe. - Название действия с сообщением. Отображаемое название, которое пользователи выбирают в меню, чтобы вызвать действие с сообщением. Его длина ограничена 50 символами. Можно использовать специальные символы. Пример:
Remind me.
- Название быстрой команды. Отображаемое название, которое пользователи выбирают в меню, чтобы вызвать команду. Может содержать до 50 символов, включая специальные. Пример:
Сообщение о загрузке (необязательно). Всплывающее уведомление, которое показывается пользователю во время выполнения действия. Доступно только для действий с сообщениями, которые не открывают диалоговые окна.
Если вы хотите, чтобы приложение Chat отвечало на команду диалоговым окном, установите флажок Открыть диалоговое окно.
Нажмите Сохранить.
Команда настроена для приложения Chat.
Сопоставление команд с вариантами запросов
Вы можете добавить команды в качестве вариантов запросов, чтобы пользователи видели их в виде интерактивных чипов, когда начинают прямую переписку с вашим приложением Chat.
Чтобы сопоставить команду с вариантом запроса:
- Убедитесь, что для команды не требуются дополнительные аргументы. В качестве вариантов запросов поддерживаются только команды с вариантами Без аргументов или Основные аргументы.
- В консоли Google Cloud перейдите на страницу Configuration (Конфигурация) Chat API.
- В разделе Интерактивные функции > Варианты запросов нажмите Добавить запрос.
- Укажите ранг (1–3) для порядка показа.
- В разделе Выбор типа нажмите Командная строка и выберите команду из раскрывающегося списка.
- Нажмите кнопку Готово, а затем – Сохранить.
Ответить на команду
Когда пользователи используют команду, ваше приложение Chat получает объект события.
Полезная нагрузка события (event.chat.appCommandPayload) содержит объект appCommandPayload с информацией о вызванной команде (включая ее идентификатор и тип), чтобы вы могли вернуть соответствующий ответ.
Объект события отправляется в конечную точку HTTP или функцию Apps Script, которую вы указали при настройке триггера команды приложения.
/help в личном чате, объясняя, как получить поддержку.Как ответить на слеш-команду или быструю команду
В примере кода ниже показано приложение Chat, которое отвечает на слеш-команду /about текстовым сообщением. Чтобы отвечать на слеш-команды или быстрые команды, приложение Chat обрабатывает объекты событий (event.chat.appCommandPayload) из триггера Команда приложения.
Когда полезная нагрузка объекта события содержит соответствующий идентификатор команды, приложение Chat возвращает действие DataActions с объектом createMessageAction (hostAppDataAction.chatDataAction.createMessageAction):
Node.js
Python
Java
Apps Script
Чтобы использовать этот пример кода, замените 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, которые используют команды
- Как отправить сообщение
- Как открыть интерактивные диалоговые окна
Приложения Chat, не являющиеся дополнениями: отвечают на команды
Приведенная ниже документация относится к приложениям Chat, которые не являются дополнениями Google Workspace. Чтобы перенести приложение Chat, которое не является дополнением, ознакомьтесь со статьей Как преобразовать приложение Google Chat в дополнение Google Workspace.
Когда пользователи используют команду, приложение Chat, которое не является дополнением, получает событие взаимодействия и может ответить, напрямую вернув объект Message.
Полезная нагрузка события содержит метаданные с подробными сведениями о вызванной команде (включая идентификатор и тип команды), чтобы вы могли вернуть соответствующий ответ.
Чтобы отвечать на каждый тип команды в приложении Chat, которое не является дополнением, необходимо обрабатывать разные типы событий и объекты метаданных в полезной нагрузке события:
| Тип команды | Тип события | Метаданные команды |
|---|---|---|
| Слеш-команда | MESSAGE |
message.slashCommand или message.annotation.slashCommand |
| Быстрая команда | APP_COMMAND |
appCommandMetadata
|
| Действие с сообщением | APP_COMMAND |
appCommandMetadata
|
Как ответить на слеш-команду
В примере кода ниже показано приложение Chat, которое не является дополнением и отвечает на слеш-команду /about. Приложение Chat обрабатывает события взаимодействия MESSAGE, определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает частный объект Message:
Node.js
Apps Script
Python
Java
Замените ABOUT_COMMAND_ID идентификатором команды, который вы указали при ее настройке в консоли Google Cloud.
Как ответить на быструю команду
В примере ниже показано приложение Chat, которое не является дополнением и отвечает на быструю команду Help. Приложение Chat обрабатывает события взаимодействия APP_COMMAND, определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает частный объект Message:
Node.js
Apps Script
Python
Java
Замените HELP_COMMAND_ID идентификатором команды, который вы указали при ее настройке в консоли Google Cloud.
Как ответить на действие с сообщением
В примере кода ниже показано приложение Chat, которое не является дополнением и отвечает на действие с сообщением Напомнить. Приложение Chat обрабатывает события взаимодействия APP_COMMAND, определяет, содержит ли событие взаимодействия соответствующий идентификатор команды, и возвращает частный объект Message:
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 handleAppCommand(event, res) {
// Collect the command ID and type from the event metadata.
const {appCommandId, appCommandType} = event.appCommandMetadata;
// Use appCommandType to detect message actions.
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.message.text;
// Return a response that includes details from the original message.
return res.send({
text: `Setting a reminder for this message: "${messageText}"`
});
}
}
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.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.message.text;
// Return a response that includes details from the original message.
return { "text": "Setting a reminder for message: " + messageText };
}
}
Python
def handle_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.
metadata = event.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 = event.get('message', {}).get('text')
# Return a response that includes details from the original message.
return {
"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 handleAppCommand(JsonObject event, HttpResponse response) throws Exception {
// Collect the command ID and type from the event metadata.
JsonObject metadata = event.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 = event.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);
response.getWriter().write(responseMessage.toString());
}
}
}
Замените REMIND_ME_COMMAND_ID идентификатором команды, который вы указали при ее настройке в консоли Google Cloud.