Odpowiadanie na polecenia aplikacji Google Chat

Uwaga: ten przewodnik wyjaśnia, jak utworzyć interaktywną aplikację do obsługi czatu za pomocą zdarzeń interakcji interfejsu Chat API. Aplikację Google Chat możesz też utworzyć jako dodatek do Google Workspace. Więcej informacji o tym, którego frameworka użyć, znajdziesz w artykule Tworzenie interaktywnej 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 Chat

Polecenia aplikacji do obsługi czatu możesz tworzyć jako polecenia po ukośniku lub polecenia szybkie. Aby odkrywać i używać poszczególnych typów poleceń, użytkownicy wykonują te czynności:

1. Polecenia rozpoczynające się ukośnikiem: użytkownicy wysyłają polecenia jako wiadomości, wpisując ukośnik (/), a potem zdefiniowany tekst, np. /about. Aplikacje do obsługi czatu mogą też wymagać tekstu argumentu dla polecenia po ukośniku. Na przykład polecenie /search może wymagać tekstu argumentu, który jest używany w zapytaniu.
2. 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.

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

• 

  Rysunek 1. Użytkownicy mogą odkrywać i używać poleceń po ukośniku, /wpisując ukośnik w obszarze odpowiedzi, a następnie nazwę polecenia.

• 
  Rysunek 2. Użytkownicy mogą odkrywać i używać szybkich poleceń z menu w obszarze odpowiedzi wiadomości na czacie.

Wymagania wstępne

Uwaga: przykładowe fragmenty kodu w tym przewodniku są napisane tak, aby działały jako funkcja Google Cloud w środowiskach Node.js, Python i Java.

Node.js

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu za pomocą usługi HTTP, wykonaj czynności opisane w tym krótkim wprowadzeniu.

Google Apps Script

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu w Apps Script, wykonaj czynności opisane w tym krótkim wprowadzeniu.

Python

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu za pomocą usługi HTTP, wykonaj czynności opisane w tym krótkim wprowadzeniu.

Java

Aplikacja Google Chat, która odbiera zdarzenia interakcji i na nie odpowiada. Aby utworzyć interaktywną aplikację do obsługi czatu za pomocą usługi HTTP, wykonaj czynności opisane w tym krótkim wprowadzeniu.

Konfigurowanie polecenia

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

1. Utwórz nazwę i opis polecenia.
2. 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ę Chat. Pod nazwą wyświetla się też krótki opis, który dodatkowo informuje użytkowników o tym, jak używać polecenia:

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 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.
• Rozważ użycie 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 Twojego polecenia jest taka sama jak w przypadku innych aplikacji do obsługi czatu, użytkownik będzie musiał 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 na czacie 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 w interfejsie Google Chat API.

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 > Google Chat API.

   Otwórz stronę interfejsu Google Chat API

2. Kliknij Konfiguracja.

3. W sekcji Polecenia kliknij Dodaj polecenie.

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

   • Identyfikator polecenia: liczba z zakresu od 1 do 1000, której aplikacja do obsługi czatu używa do rozpoznawania polecenia i zwracania odpowiedzi.
   • Opis: tekst opisujący działanie polecenia. Opis może zawierać maksymalnie 50 znaków, w tym znaki specjalne.
   • Typ polecenia: wybierz Szybkie polecenie lub Polecenie po ukośniku.
   • 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.

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

6. Kliknij Zapisz.

Polecenie jest teraz skonfigurowane dla aplikacji Google Chat.

Odpowiadanie na polecenie

Więcej przykładów znajdziesz w artykule Przykłady aplikacji Google Chat.

Gdy użytkownicy używają polecenia, aplikacja do obsługi czatu otrzymuje zdarzenie interakcji. Ł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ź.

Aplikacja Google Chat odpowiada prywatnie na polecenie z ukośnikiem /help, aby wyjaśnić, jak uzyskać pomoc.

Aby reagować na poszczególne typy poleceń, 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

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

Odpowiadanie na polecenie po ukośniku

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

Node.js

node/avatar-app/index.js

Wyświetl w GitHubie

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

Google Apps Script

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

Wyświetl w GitHubie

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

python/avatar-app/main.py

Wyświetl w GitHubie

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

java/avatar-app/src/main/java/AvatarApp.java

Wyświetl w GitHubie

/**
 * 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 określonym podczas konfigurowania polecenia w konsoli Google Cloud.

Odpowiadanie na szybkie polecenie

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

Node.js

node/avatar-app/index.js

Wyświetl w GitHubie

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

Google Apps Script

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

Wyświetl w GitHubie

/**
 * Handles the APP_COMMAND event type. This function is triggered when a user
 * interacts with a quick command within the Google Chat app.  It responds
 * based on the command ID.
 *
 * @param {Object} event The event object from Google Chat, containing details
 *     about the app command interaction.  It includes information like the
 *     command ID and the user who triggered it.
 */
function onAppCommand(event) {
  // Executes the quick command logic based on its ID.
  // Command IDs are set in the Google Chat API configuration.
  switch (event.appCommandMetadata.appCommandId) {
    case HELP_COMMAND_ID:
      return {
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

Python

python/avatar-app/main.py

Wyświetl w GitHubie

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

java/avatar-app/src/main/java/AvatarApp.java

Wyświetl w GitHubie

/**
 * 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 określonym podczas konfigurowania polecenia w konsoli Google Cloud.

Testowanie polecenia

Aby przetestować polecenie i kod, zapoznaj się z artykułem Testowanie funkcji interaktywnych aplikacji 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.

Powiązane artykuły

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