Odpowiadanie na polecenia aplikacji Google Chat

Z tej strony dowiesz się, jak skonfigurować i odpowiadać na polecenia w aplikacji Google Chat.

Polecenia pomagają użytkownikom odkrywać i korzystać z 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, będzie ona widoczna tylko dla niego i aplikacji czatu.

Aby zdecydować, czy chcesz tworzyć polecenia, i poznać sposób projektowania interakcji z użytkownikiem, przeczytaj artykuł Definiowanie wszystkich ścieżek użytkownika.

Typy poleceń w Google Chat

Polecenia aplikacji Google Chat możesz tworzyć jako polecenia po ukośniku lub szybkie polecenia. Aby odkryć i używać poszczególnych typów poleceń, użytkownicy muszą:
  1. Polecenia rozpoczynające się ukośnikiem: użytkownicy wysyłają polecenia w postaci wiadomości, wpisując ukośnik (/), a następnie wstępny tekst, np. /about. Aplikacje do obsługi czatu mogą też wymagać tekstu argumentu dla polecenia po ukośniku. Na przykład polecenie ukośnikiem /search może wymagać tekstu argumentu, który jest używany do zapytania wyszukiwania.
  2. Szybkie polecenia: użytkownicy używają poleceń, otwierając menu w obszarze odpowiedzi wiadomości w Google Chat. Aby użyć polecenia, użytkownik klika Dodaj i wybiera polecenie z menu.
Na tych obrazach widać, jak użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń:
  • Użytkownik odkrywa polecenia po ukośniku.
    Rysunek 1. Użytkownicy odkrywają i korzystają z poleceń po ukośniku, wpisując ukośnik / w obszarze odpowiedzi, a następnie nazwę polecenia.
  • Użytkownik wyświetla szybkie polecenia w menu.
    Rysunek 2. Użytkownicy mogą odkrywać i korzystać z szybkich poleceń w menu w obszarze odpowiedzi wiadomości w Google Chat.

Wymagania wstępne

Node.jsGoogle Apps ScriptPythonJava

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat w Apps Script, wykonaj krótkie wprowadzenie.

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Aplikacja Google Chat, w której włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację Google Chat za pomocą usługi HTTP, wykonaj to krótkie wprowadzenie.

Konfigurowanie polecenia

W tej sekcji opisaliśmy, jak skonfigurować tę komendę:

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

Nazwij i opisz polecenie

Nazwa polecenia to to, co użytkownicy wpisują lub wybierają, aby wywołać aplikację Google Chat. Pod nazwą pojawia się też krótki opis, który informuje użytkowników, jak korzystać z polecenia:

Nazwa i opis polecenia po ukośniku
Ilustracja 3. Nazwa i opis polecenia po ukośniku.

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

Aby nazwać polecenie:

  • Używaj krótkich, opisowych i użytecznych słów lub wyrażeń, aby polecenia były zrozumiałe dla użytkownika. Na przykład zamiast nazwy Create a reminder użyj Remind me.
  • Rozważ użycie unikalnej lub wspólnej nazwy polecenia. Jeśli Twoje polecenie opisuje typowe interakcje lub funkcje, możesz użyć powszechnej nazwy, którą użytkownicy znają i oczekują, takiej jak Settings lub Feedback. W przeciwnym razie używaj unikalnych nazw poleceń, ponieważ jeśli nazwa polecenia jest taka sama w przypadku innych aplikacji do czatu, użytkownik musi przefiltrować 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 argumentu tekstowego, w opisie wpisz coś w rodzaju Remind me to do [something] at [time].
  • Poinformuj użytkowników, czy aplikacja Google Chat ma odpowiadać wszystkim użytkownikom w pokoju, czy tylko użytkownikowi, który wywołał polecenie. Na przykład w przypadku szybkiego polecenia About możesz je opisać jako Learn about this app (Only visible to you).

Konfigurowanie polecenia w konsoli Google Cloud

Aby utworzyć polecenie po ukośniku lub szybkie polecenie, podaj informacje o nim w konfiguracji interfejsu Google Chat API w aplikacji Google Chat.

Aby skonfigurować polecenie w Google Chat API, wykonaj te czynności:

  1. W konsoli Google Cloud kliknij Menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Interfejs Google Chat API

    Otwórz stronę interfejsu Google Chat API

  2. Kliknij Konfiguracja.

  3. W sekcji Polecenia kliknij Dodaj polecenie.

  4. Wpisz identyfikator, nazwę, opis i typ polecenia:

    • Identyfikator polecenia: liczba z zakresu 1–1000, której używa aplikacja Google Chat do rozpoznawania polecenia i zwracania odpowiedzi.
    • Nazwa: wyświetlana nazwa polecenia. Nazwy mogą mieć maksymalnie 50 znaków i mogą zawierać znaki specjalne.
    • Opis: tekst opisujący działanie polecenia. Opis może mieć maksymalnie 50 znaków i może zawierać znaki specjalne.
    • Typ polecenia: wybierz Szybkie polecenie lub Polecenie po ukośniku.
    • Jeśli konfigurujesz polecenie po ukośniku, wpisz wartość w polu Nazwa polecenia po ukośniku, aby określić, co użytkownicy muszą wpisać, aby wywołać to polecenie. Musi zaczynać się od ukośnika, zawierać tylko tekst i mieć maksymalnie 50 znaków. Na przykład: /remindMe.

  5. Opcjonalnie: jeśli chcesz, aby aplikacja Google Chat odpowiadała na polecenie za pomocą okna dialogowego, zaznacz pole wyboru Otwórz okno dialogowe.

  6. Kliknij Zapisz.

Polecenie zostało skonfigurowane w aplikacji Google Chat.

Odpowiedź na polecenie

Gdy użytkownicy używają polecenia, aplikacja Google Chat otrzymuje zdarzenie interakcji. Ładunek zdarzenia zawiera metadane z szczegółami wywołanego polecenia (w tym identyfikator i typ polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź.

Prywatna wiadomość dotycząca aplikacji Google Chat firmy Cymbal Labs. W wiadomości podano, że aplikacja Google Chat została stworzona przez Cymbal Labs, oraz podano link do dokumentacji i kontakt do zespołu pomocy.
Aplikacja Google Chat odpowiada prywatnie na komendę /help, aby wyjaśnić, jak uzyskać pomoc.

Aby odpowiedzieć na każdy typ polecenia, musisz obsłużyć 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

Aby dowiedzieć się, jak odpowiedzieć na polecenie za pomocą wiadomości, zapoznaj się z sekcjami poniżej.

Odpowiedź na polecenie po ukośniku

Poniższy kod pokazuje przykład aplikacji czatu, która odpowiada na polecenie /about. Aplikacja Google Chat obsługuje zdarzenia interakcji MESSAGE, wykrywa, czy zdarzenie interakcji zawiera pasujący identyfikator polecenia, i zwraca wiadomość prywatną:

Node.js Google Apps Script Python Java
node/avatar-app/index.js
/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}
apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}
python/avatar-app/main.py
def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}
java/avatar-app/src/main/java/AvatarApp.java
/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Zastąp ABOUT_COMMAND_ID identyfikatorem polecenia, który został podany podczas konfigurowania polecenia w konsoli Google Cloud.

Odpowiedź na szybkie polecenie

Poniższy kod pokazuje przykład aplikacji czatu, która odpowiada na szybkie polecenie Pomoc. Aplikacja Google Chat obsługuje zdarzenia interakcji APP_COMMAND, wykrywa, czy zdarzenie interakcji zawiera pasujący identyfikator polecenia, i zwraca wiadomość prywatną:

Node.js Google Apps Script Python Java
node/avatar-app/index.js
/**
 * Handles slash and quick commands.
 *
 * @param {Object} event - The Google Chat event.
 * @param {Object} res - The HTTP response object.
 */
function handleAppCommands(event, res) {
  const {appCommandId, appCommandType} = event.appCommandMetadata;

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
    case HELP_COMMAND_ID:
      return res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}
apps-script/avatar-app/avatar-app.gs
// Checks for the presence of a slash command in the message.
if (event.message.slashCommand) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (event.message.slashCommand.commandId) {
    case ABOUT_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}
python/avatar-app/main.py
def handle_app_commands(event: Mapping[str, Any]) -> Mapping[str, Any]:
    """Handles slash and quick commands.

    Args:
        Mapping[str, Any] event: The Google Chat event.

    Returns:
        Mapping[str, Any]: the response
    """
    app_command_id = event["appCommandMetadata"]["appCommandId"]

    if app_command_id == ABOUT_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    elif app_command_id == HELP_COMMAND_ID:
        return {
            "privateMessageViewer": event["user"],
            "text": "The Avatar app replies to Google Chat messages.",
        }
    return {}
java/avatar-app/src/main/java/AvatarApp.java
/**
 * Handles slash and quick commands.
 *
 * @param event    The Google Chat event.
 * @param response The HTTP response object.
 */
private void handleAppCommands(JsonObject event, HttpResponse response) throws Exception {
  int appCommandId = event.getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt();

  switch (appCommandId) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      return;
    case HELP_COMMAND_ID:
      Message helpMessage = new Message();
      helpMessage.setText("The Avatar app replies to Google Chat messages.");
      helpMessage.setPrivateMessageViewer(new User()
          .setName(event.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(helpMessage));
      return;
  }
}

Zastąp HELP_COMMAND_ID identyfikatorem polecenia, który został podany podczas konfigurowania polecenia w konsoli Google Cloud.

Testowanie polecenia

Aby przetestować polecenie i kod, zapoznaj się z artykułem Testowanie interaktywnych funkcji aplikacji Google Chat.

Aby dowiedzieć się, jak przetestować i używać komendy w interfejsie Google Chat, zapoznaj się z artykułem Korzystanie z aplikacji w Google Chat w dokumentacji Google Chat.