Odpowiadanie na polecenia aplikacji Google Chat

Z tego artykułu dowiesz się, jak skonfigurować polecenia i na nie odpowiadać jako aplikacja Google Chat.

Polecenia pomagają użytkownikom odkrywać i korzystać z najważniejszych funkcji aplikacji do obsługi czatu. Tylko aplikacje do obsługi czatu mogą wyświetlać treść polecenia. Jeśli na przykład użytkownik wyśle wiadomość z poleceniem z ukośnikiem, będzie ona widoczna tylko dla niego i aplikacji do czatu.

Aby zdecydować, czy warto tworzyć polecenia, i dowiedzieć się, jak projektować interakcje użytkowników, zapoznaj się z artykułem Określanie wszystkich ścieżek użytkownika.

Typy poleceń aplikacji Google Chat

Polecenia aplikacji w Google Chat możesz tworzyć jako polecenia po ukośniku lub polecenia szybkie. Aby odkrywać polecenia, użytkownicy mogą wpisać ukośnik / w obszarze odpowiedzi lub kliknąć Narzędzia Google Workspace

w obszarze odpowiedzi wiadomości w Google Chat. Aby użyć każdego typu polecenia, 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 zdefiniowany tekst, np. /about. Aplikacje do obsługi czatu zwykle wymagają tekstu argumentu dla polecenia po ukośniku.

Utwórz polecenie po ukośniku, jeśli aplikacja w Google Chat wymaga dodatkowych danych wejściowych od użytkownika. Możesz na przykład utworzyć polecenie po ukośniku o nazwie /search, które będzie uruchamiane po wpisaniu przez użytkownika frazy do wyszukania, np. /search receipts.
Szybkie polecenia: użytkownicy mogą używać poleceń, otwierając menu w obszarze odpowiedzi wiadomości na czacie. Aby użyć polecenia, klikają Dodaj i wybierają polecenie z menu.

Utwórz szybkie polecenie, jeśli aplikacja do obsługi czatu może od razu odpowiedzieć użytkownikowi bez czekania na dodatkowe dane wejściowe. Możesz na przykład utworzyć szybkie polecenie o nazwie Losowy obraz, które od razu odpowie obrazem.

Na tym obrazie pokazujemy, jak użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń:

Użytkownik odkrywa menu poleceń po ukośniku i szybkich poleceń. — Użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń.

Wymagania wstępne

HTTP

Dodatek do Google Workspace, który rozszerza Google Chat. Aby go utworzyć, wykonaj czynności opisane w tym krótkim wprowadzeniu dotyczącym HTTP.

Google Apps Script

Dodatek do Google Workspace, który rozszerza Google Chat. Aby go utworzyć, wykonaj czynności opisane w krótkim wprowadzeniu do Apps Script.

Konfigurowanie polecenia

Z tej sekcji dowiesz się, jak wykonać te czynności, aby skonfigurować polecenie:

Utwórz nazwę i opis polecenia.
Skonfiguruj polecenie w konsoli Google Cloud.

Nazwij i opisz polecenie

Nazwa polecenia to tekst, który użytkownicy wpisują lub wybierają, aby wywołać aplikację do obsługi czatu. Pod nazwą wyświetla się też krótki opis, który podpowiada użytkownikom, jak używać polecenia:

Wybierając nazwę i opis polecenia, weź pod uwagę te zalecenia:

Aby nazwać polecenie:

Używaj krótkich, opisowych i zachęcających do działania słów lub zwrotów, aby polecenia były zrozumiałe dla użytkownika. Na przykład zamiast nazwy Create a reminder użyj Remind me.
Użyj unikalnej lub powszechnie znanej nazwy polecenia. Jeśli polecenie opisuje typową interakcję lub funkcję, możesz użyć powszechnie znanej nazwy, której użytkownicy oczekują, np. Settings lub Feedback. W przeciwnym razie staraj się używać unikalnych nazw poleceń, ponieważ jeśli nazwa polecenia jest taka sama w przypadku innych aplikacji do obsługi czatu, 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 ma jakieś wymagania dotyczące formatowania. Jeśli na przykład utworzysz polecenie po ukośniku, które wymaga tekstu argumentu, ustaw opis na coś w rodzaju Remind me to do [something] at [time].
Poinformuj użytkowników, czy aplikacja Google Chat odpowiada wszystkim osobom w pokoju, czy prywatnie użytkownikowi, który wywołał polecenie. Na przykład szybkie polecenie About możesz opisać jako Learn about this app (Only visible to you).

Konfigurowanie polecenia w konsoli Google Cloud

Aby utworzyć polecenie po ukośniku lub polecenie szybkie, podaj informacje o poleceniu w konfiguracji aplikacji do obsługi czatu 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.

Otwórz stronę interfejsu Google Chat API
Kliknij Konfiguracja.
W sekcji Ustawienia połączenia otwórz Aktywatory i podaj szczegóły punktu końcowego. W następnej sekcji musisz użyć tego aktywatora, aby odpowiedzieć na polecenie.
1. URL punktu końcowego HTTP: możesz tu 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, określ punkt końcowy bezpośrednio w polu Polecenie aplikacji.
2. Apps Script: wpisz identyfikator wdrożenia Apps Script. Domyślnie wywoływana jest funkcja onAppCommand. Aby użyć innej funkcji Apps Script, w polu Polecenie aplikacji wpisz nazwę funkcji niestandardowej.
W sekcji Polecenia kliknij Dodaj polecenie.
Podaj te informacje o poleceniu:
1. Identyfikator polecenia: liczba z zakresu od 1 do 1000, której aplikacja do obsługi czatu używa do rozpoznawania polecenia i zwracania odpowiedzi.
2. Opis: tekst opisujący sposób używania i formatowania polecenia. Opis może zawierać maksymalnie 50 znaków.
3. Typ polecenia: wybierz Szybkie polecenie lub Polecenie po ukośniku.
4. Podaj nazwę szybkiego polecenia lub polecenia po ukośniku:
  - Nazwa szybkiego polecenia: nazwa wyświetlana, którą użytkownicy wybierają z menu, aby wywołać polecenie. Może zawierać do 50 znaków, w tym 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 może mieć maksymalnie 50 znaków. Na przykład: /remindMe.
Opcjonalnie: jeśli chcesz, aby aplikacja 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.

Odpowiadanie na polecenie

Gdy użytkownicy używają polecenia, aplikacja do obsługi czatu otrzymuje obiekt zdarzenia. Ładunek zdarzenia zawiera obiekt appCommandPayload z informacjami o wywołanym poleceniu (w tym identyfikator i typ polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź. Obiekt zdarzenia jest wysyłany do punktu końcowego HTTP lub funkcji Apps Script, które zostały określone podczas konfigurowania wyzwalacza Polecenie aplikacji.

Wiadomość prywatna w aplikacji Cymbal Labs Chat. Wiadomość informuje, że aplikacja Chat została utworzona przez Cymbal Labs, i zawiera link do dokumentacji oraz link do zespołu pomocy. — Aplikacja Google Chat odpowiada prywatnie na polecenie po ukośniku `/help`, aby wyjaśnić, jak uzyskać pomoc.

Poniższy kod pokazuje przykład aplikacji w Google Chat, która odpowiada na polecenie po ukośniku /about wiadomością tekstową. Aby odpowiadać na polecenia po ukośniku, aplikacja do obsługi czatu przetwarza obiekty zdarzeń z aktywatora Polecenie aplikacji. Gdy ładunek obiektu zdarzenia zawiera identyfikator polecenia po ukośniku, aplikacja w Google Chat zwraca działanie DataActions z obiektem createMessageAction:

Node.js

node/chat/avatar-app/index.js

Wyświetl w GitHubie

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

Wyświetl w GitHubie

# 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

Wyświetl w GitHubie

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

Google Apps Script

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

Wyświetl w GitHubie

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

Aby użyć tego przykładowego kodu, zastąp symbol ABOUT_COMMAND_ID identyfikatorem polecenia, który został określony 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ć i używać polecenia w interfejsie Chat, zapoznaj się z artykułem Korzystanie z aplikacji w Google Chat w dokumentacji pomocy Google Chat.

Wyświetl przykłady aplikacji do Google Chat, które używają poleceń.
Wyślij wiadomość
Otwieranie interaktywnych okien

Odpowiadanie na polecenia aplikacji Google Chat Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Typy poleceń aplikacji Google Chat

Wymagania wstępne

HTTP

Google Apps Script

Konfigurowanie polecenia

Nazwij i opisz polecenie

Aby nazwać polecenie:

Aby opisać polecenie:

Konfigurowanie polecenia w konsoli Google Cloud

Odpowiadanie na polecenie

Node.js

Python

Java

Google Apps Script

Testowanie polecenia

Powiązane artykuły

Odpowiadanie na polecenia aplikacji Google Chat