Na tej stronie dowiesz się, jak skonfigurować polecenia i odpowiadać na nie jako aplikacja Google Chat.
Polecenia pomagają użytkownikom odkrywać i używać kluczowych funkcji aplikacji Google Chat. Tylko aplikacje Google Chat mogą wyświetlać treść polecenia. Jeśli na przykład użytkownik wyśle wiadomość z poleceniem po ukośniku, będzie ona widoczna tylko dla niego i aplikacji Google Chat.
Aby zdecydować, czy chcesz tworzyć polecenia, i dowiedzieć się, jak projektować interakcje użytkowników, zapoznaj się z artykułem Definiowanie wszystkich ścieżek użytkownika.
Typy poleceń aplikacji do Google Chat
Polecenia aplikacji Google Chat możesz tworzyć jako polecenia po ukośniku, szybkie polecenia lub działania związane z wiadomościami. Aby użyć poszczególnych typów poleceń, użytkownicy mogą wykonać te czynności:-
Polecenia po ukośniku: użytkownicy mogą wybrać polecenie po ukośniku z menu lub wpisać ukośnik (
/), a następnie wstępnie zdefiniowany tekst, np./about. Aplikacje do obsługi czatu zwykle wymagają tekstu argumentu polecenia po ukośniku.Utwórz polecenie po ukośniku, jeśli aplikacja do Google Chat wymaga dodatkowych danych od użytkownika. Możesz na przykład utworzyć polecenie po ukośniku o nazwie
/search, które będzie uruchamiane, gdy użytkownik wpisze wyszukiwane hasło, np./search receipts. -
Szybkie polecenia: użytkownicy używają poleceń, otwierając menu w obszarze odpowiedzi wiadomości na czacie. Aby użyć polecenia, kliknij Dodaj
i wybierz polecenie z menu.
Utwórz szybkie polecenie, jeśli aplikacja do Google Chat może natychmiast odpowiedzieć użytkownikowi bez czekania na dodatkowe dane wejściowe. Możesz na przykład utworzyć szybkie polecenie o nazwie Losowy obraz, które natychmiast odpowiada obrazem.
-
Działania na wiadomościach: użytkownicy mogą korzystać z działań na wiadomościach, najeżdżając kursorem na wiadomość i klikając menu z 3 kropkami. Aby użyć polecenia, otwórz menu z 3 kropkami i wybierz polecenie z menu.
Jeśli aplikacja do Google Chat może wykonywać działania na podstawie kontekstu wiadomości, utwórz działanie na wiadomości.
Te obrazy pokazują, jak użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń oraz działań na wiadomościach:
Wymagania wstępne
HTTP
aplikację Google Chat, która odbiera interakcje użytkowników i na nie odpowiada; Aby ją utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do HTTP.
Google Apps Script
aplikację Google Chat, która odbiera interakcje użytkowników i na nie odpowiada; Aby go utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do Apps Script.
Konfigurowanie polecenia
W tej sekcji dowiesz się, jak wykonać te czynności, aby skonfigurować polecenie:
- Utwórz nazwę i opis polecenia.
- Skonfiguruj polecenie w konsoli Google Cloud.
- Opcjonalnie: mapowanie poleceń na prompty początkowe.
Nazwij i opisz polecenie
Nazwa polecenia to tekst, który użytkownicy wpisują lub wybierają, aby wywołać aplikację Google Chat. Pod nazwą wyświetla się też krótki opis, który zawiera dodatkowe informacje o tym, jak używać polecenia:
Wybierając nazwę i opis polecenia, weź pod uwagę te zalecenia:
Aby nazwać polecenie:
- Używaj krótkich, opisowych i praktycznych słów lub wyrażeń, aby polecenia były jasne dla użytkownika. Na przykład zamiast nazwy
Create a reminderużyjRemind me. - Rozważ użycie unikalnej lub popularnej nazwy polecenia. Jeśli polecenie opisuje typową interakcję lub funkcję, możesz użyć popularnej nazwy, którą użytkownicy rozpoznają i której oczekują, np.
SettingslubFeedback. W przeciwnym razie spróbuj użyć unikalnych nazw poleceń, ponieważ jeśli nazwa polecenia jest taka sama jak w innych aplikacjach Google Chat, użytkownik musi filtrować podobne polecenia, aby znaleźć i użyć Twojego.
Aby opisać polecenie:
- Opis powinien być krótki i jasny, aby użytkownicy wiedzieli, czego mogą się spodziewać po użyciu polecenia.
- Poinformuj użytkowników, czy polecenie wymaga określonego formatowania. Jeśli na przykład tworzysz polecenie po ukośniku, które wymaga tekstu argumentu, ustaw opis na coś takiego:
Remind me to do [something] at [time]. - Poinformuj użytkowników, czy aplikacja do Google Chat odpowiada wszystkim osobom w pokoju, czy prywatnie użytkownikowi, który wywołał polecenie. Na przykład w przypadku szybkiego polecenia
Aboutmożesz opisać je jakoLearn about this app (Only visible to you).
Konfigurowanie polecenia w konsoli Google Cloud
Aby utworzyć polecenie po ukośniku, szybkie polecenie lub działanie na wiadomości, musisz podać informacje o poleceniu lub działaniu w konfiguracji aplikacji Google Chat dla interfejsu Google Chat API.
Aby skonfigurować polecenie w Google Chat API, wykonaj te czynności:
W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Google Chat API.
Kliknij Konfiguracja.
W sekcji Ustawienia połączenia kliknij Aktywatory i podaj szczegóły punktu końcowego. Musisz użyć tego aktywatora w następnej sekcji, aby odpowiedzieć na polecenie.
- Adres URL punktu końcowego HTTP: tutaj możesz określić jeden wspólny adres URL punktu końcowego HTTP. Jeśli chcesz używać różnych punktów końcowych HTTP dla różnych aktywatorów, możesz też określić punkt końcowy bezpośrednio w polu Polecenie aplikacji.
- Apps Script: wpisz identyfikator wdrożenia Apps Script. Domyślnie zostanie wywołana funkcja
onAppCommand. Aby użyć innej funkcji Apps Script, wpisz nazwę funkcji niestandardowej w polu Polecenie aplikacji.
W sekcji Polecenia kliknij Dodaj polecenie.
Podaj te informacje o poleceniu:
- Identyfikator polecenia: liczba od 1 do 1000, której aplikacja Google Chat używa do rozpoznawania polecenia i zwracania odpowiedzi.
- Opis: tekst opisujący sposób użycia i formatowania polecenia. Opis może zawierać maksymalnie 50 znaków.
- Typ polecenia: wybierz Szybkie polecenie, Polecenie po ukośniku lub Działanie na wiadomości.
- Podaj nazwę polecenia:
- Nazwa szybkiego polecenia: wyświetlana nazwa, którą użytkownicy wybierają z menu, aby wywołać polecenie. Może mieć do 50 znaków i zawierać znaki specjalne. Na przykład:
Remind me. - Nazwa polecenia po ukośniku: tekst, który użytkownicy wpisują, aby wywołać polecenie w wiadomości. Musi zaczynać się od ukośnika, zawierać tylko tekst i mieć maksymalnie 50 znaków. Na przykład:
/remindMe. - Nazwa działania związanego z wiadomością: wyświetlana nazwa, którą użytkownicy wybierają z menu, aby wywołać działanie związane z wiadomością. Może zawierać do 50 znaków, w tym znaki specjalne. Na przykład:
Remind me.
- Nazwa szybkiego polecenia: wyświetlana nazwa, którą użytkownicy wybierają z menu, aby wywołać polecenie. Może mieć do 50 znaków i zawierać znaki specjalne. Na przykład:
Opcjonalnie: Wiadomość z powiadomieniem o wczytywaniu: wiadomość z powiadomieniem, która wyświetla się użytkownikowi podczas wykonywania działania związanego z wiadomością. Dostępne tylko w przypadku działań na wiadomościach, które nie otwierają okien.
Opcjonalnie: jeśli chcesz, aby aplikacja do Google Chat odpowiadała na polecenie za pomocą okna, zaznacz pole wyboru Otwórz okno.
Kliknij Zapisz.
Polecenie jest teraz skonfigurowane dla aplikacji Google Chat.
Mapowanie poleceń na prompty początkowe
Możesz wyświetlać polecenia jako prompty początkowe, aby użytkownicy widzieli je jako interaktywne elementy, gdy rozpoczynają pusty czat indywidualny z aplikacją do Google Chat.
Aby zmapować polecenie na prompt początkowy:
- Upewnij się, że polecenie nie wymaga dodatkowych argumentów niestandardowych (jako prompty początkowe obsługiwane są tylko polecenia z opcją Bez argumentów lub Podstawowe argumenty).
- W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API.
- W sekcji Funkcje interaktywne > Prompty początkowe kliknij Dodaj prompt.
- Ustaw pozycję (1–3), aby określić kolejność wyświetlania.
- W sekcji Wybór typu kliknij Znak zachęty i wybierz polecenie z menu.
- Kliknij kolejno Gotowe i Zapisz.
Odpowiadanie na polecenie
Gdy użytkownicy używają polecenia, aplikacja Google Chat otrzymuje obiekt zdarzenia.
Ładunek zdarzenia (event.chat.appCommandPayload) zawiera obiekt appCommandPayload ze szczegółami wywołanego polecenia (w tym identyfikatorem i typem polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź.
Obiekt zdarzenia jest wysyłany do punktu końcowego HTTP lub funkcji Apps Script określonej podczas konfigurowania aktywatora polecenia aplikacji.
/help, aby wyjaśnić, jak uzyskać pomoc.Odpowiadanie na polecenie po ukośniku lub szybkie polecenie
Poniższy kod pokazuje przykład aplikacji Google Chat, która odpowiada na polecenie po ukośniku /about wiadomością tekstową. Aby odpowiadać na polecenia po ukośniku lub szybkie polecenia, aplikacja Google Chat obsługuje obiekty zdarzeń (event.chat.appCommandPayload) z aktywatora Polecenie aplikacji.
Gdy ładunek obiektu zdarzenia zawiera pasujący identyfikator polecenia, aplikacja Google Chat zwraca działanie DataActions z obiektem createMessageAction (hostAppDataAction.chatDataAction.createMessageAction):
Node.js
Python
Java
Google Apps Script
Aby użyć tego przykładowego kodu, zastąp ABOUT_COMMAND_ID identyfikatorem polecenia podanym podczas konfigurowania polecenia w interfejsie Chat API.
Odpowiadanie na działanie związane z wiadomością
Poniższy kod pokazuje przykład aplikacji Google Chat, która odpowiada na działanie na wiadomości Przypomnij mi za pomocą SMS-a. Aby odpowiadać na działania związane z wiadomościami, aplikacja Google Chat obsługuje obiekty zdarzeń z aktywatora Polecenie aplikacji. Gdy ładunek obiektu zdarzenia zawiera identyfikator polecenia działania związanego z wiadomością, aplikacja Google Chat zwraca działanie DataActions z obiektem 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());
}
}
}
Google 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();
}
}
Aby użyć tego przykładowego kodu, zastąp REMIND_ME_COMMAND_ID identyfikatorem polecenia określonym podczas konfigurowania polecenia w interfejsie Chat API.
Testowanie polecenia
Aby przetestować polecenie i kod, zapoznaj się z artykułem Testowanie funkcji interaktywnych w aplikacjach Google Chat.
Aby dowiedzieć się, jak przetestować polecenie i używać go w interfejsie Google Chat, zapoznaj się z artykułem Korzystanie z aplikacji w Google Chat w dokumentacji pomocy Google Chat.
Powiązane artykuły
- Zobacz przykłady aplikacji do Google Chat, które używają poleceń.
- Wyślij wiadomość
- Otwieranie interaktywnych okien
Aplikacje do Google Chat, które nie są dodatkami: odpowiadanie na polecenia
Poniższa dokumentacja dotyczy aplikacji do Google Chat, które nie są dodatkami do Google Workspace. Aby dowiedzieć się, jak przenieść aplikację Google Chat, która nie jest dodatkiem, przeczytaj artykuł Przekształcanie aplikacji Google Chat w dodatek do Google Workspace.
Gdy użytkownicy używają polecenia, aplikacja do Google Chat, która nie jest dodatkiem, otrzymuje zdarzenie interakcji i może odpowiedzieć, zwracając bezpośrednio obiekt Message.
Ładunek zdarzenia zawiera metadane ze szczegółami wywołanego polecenia (w tym identyfikator i typ polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź.
Aby odpowiadać na każdy typ polecenia w aplikacji Google Chat, która nie jest dodatkiem, musisz obsługiwać różne typy zdarzeń i obiekty metadanych w ładunku zdarzenia:
| Typ polecenia | Typ zdarzenia | Metadane polecenia |
|---|---|---|
| Polecenie po ukośniku | MESSAGE |
message.slashCommand lub message.annotation.slashCommand |
| Szybkie polecenie | APP_COMMAND |
appCommandMetadata
|
| Działanie związane z wiadomością | APP_COMMAND |
appCommandMetadata
|
Odpowiadanie na polecenie po ukośniku
Poniższy kod pokazuje przykład aplikacji Google Chat, która nie jest dodatkiem i odpowiada na polecenie po ukośniku /about. Aplikacja Google Chat obsługuje zdarzenia interakcji MESSAGE, wykrywa, czy zdarzenie interakcji zawiera pasujący identyfikator polecenia, i zwraca obiekt prywatny Message:
Node.js
Google Apps Script
Python
Java
Zastąp ABOUT_COMMAND_ID identyfikatorem polecenia określonym podczas konfigurowania polecenia w konsoli Google Cloud.
Odpowiadanie na szybkie polecenie
Poniższy kod pokazuje przykład aplikacji Google Chat, która nie jest dodatkiem, odpowiadającej na szybkie polecenie Help. Aplikacja Google Chat obsługuje zdarzenia interakcji APP_COMMAND, wykrywa, czy zdarzenie interakcji zawiera pasujący identyfikator polecenia, i zwraca obiekt prywatny Message:
Node.js
Google Apps Script
Python
Java
Zastąp HELP_COMMAND_ID identyfikatorem polecenia określonym podczas konfigurowania polecenia w konsoli Google Cloud.
Odpowiadanie na działanie związane z wiadomością
Poniższy kod pokazuje przykład aplikacji Google Chat, która nie jest dodatkiem i odpowiada na działanie związane z wiadomością Przypomnij mi. Aplikacja Google Chat obsługuje zdarzenia interakcji APP_COMMAND, wykrywa, czy zdarzenie interakcji zawiera pasujący identyfikator polecenia, i zwraca prywatny obiekt 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}"`
});
}
}
Google 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());
}
}
}
Zastąp REMIND_ME_COMMAND_ID identyfikatorem polecenia określonym podczas konfigurowania polecenia w konsoli Google Cloud.