Odpowiadanie na polecenia aplikacji Google Chat

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

Polecenia pomagają użytkownikom odkrywać i używać najważniejszych 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 tworzyć polecenia, i dowiedzieć się, jak projektować interakcje z użytkownikami, przeczytaj artykuł Określanie wszystkich ścieżek użytkownika.

Typy poleceń aplikacji Google Chat

1. Polecenia po ukośniku: użytkownicy mogą wybrać polecenie po ukośniku z menu lub wpisać ukośnik (/), a następnie predefiniowany tekst, np. /about. Aplikacje Google Chat zwykle wymagają tekstu argumentu dla polecenia po ukośniku.

   Utwórz polecenie po ukośniku, jeśli aplikacja 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 uruchamia się, gdy użytkownik wpisze frazę do wyszukania, np. /search receipts.

2. Szybkie polecenia: użytkownicy używają poleceń, otwierając menu w obszarze odpowiedzi wiadomości w Google Chat. Aby użyć polecenia, klikają Dodaj i wybierają polecenie z menu.

   Utwórz szybkie polecenie, jeśli aplikacja 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.

3. Działania związane z wiadomością: (science wersja przedpremierowa dla programistów) użytkownicy używają działań związanych z wiadomością, najeżdżając kursorem na wiadomość i klikając menu z 3 kropkami. Aby użyć polecenia, otwierają menu z 3 kropkami i wybierają polecenie z menu.

   Utwórz działanie związane z wiadomością, jeśli aplikacja Google Chat może wykonywać działania na podstawie na podstawie kontekstu wiadomości.

Na ilustracjach poniżej pokazujemy, jak użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń oraz działań związanych z wiadomością:

Wymagania wstępne

Konfigurowanie polecenia

W 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.

Nadawanie nazwy i opisywanie polecenia

Nazwa polecenia to tekst, który użytkownicy wpisują lub wybierają, aby wywołać aplikację Google Chat. Krótki opis pojawia się też pod nazwą, aby dodatkowo zachęcić użytkowników do korzystania z 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 fraz, aby polecenia były jasne dla użytkownika. Zamiast nazwy Create a reminder użyj na przykład Remind 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 się spodziewają, np. Settings lub Feedback. 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 się spodziewać, gdy użyją 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ś takiego jak Remind me to do [something] at [time].
• Poinformuj użytkowników, czy aplikacja Google Chat odpowiada wszystkim w pokoju, czy prywatnie użytkownikowi, który wywołał polecenie. Na przykład w przypadku szybkiego polecenia About, możesz opisać je jako Learn about this app (Only visible to you).

Konfigurowanie polecenia w konsoli Google Cloud

Aby utworzyć polecenie po ukośniku, szybkie polecenie lub działanie związane z wiadomością, musisz określić informacje o poleceniu lub działaniu w konfiguracji aplikacji Google Chat w interfejsie Google Chat API.

Aby skonfigurować polecenie w interfejsie Google Chat API:

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

   Otwórz stronę 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 od 1 do 1000, której aplikacja Google Chat używa do rozpoznawania polecenia i zwracania odpowiedzi.
   • Opis: tekst opisujący, co robi polecenie. Opisy mogą mieć maksymalnie 50 znaków i zawierać znaki specjalne.
   • Typ polecenia: wybierz Szybkie polecenie, Polecenie po ukośniku lub Działanie związane z wiadomością.
   • Określ nazwę polecenia:
     • Nazwa szybkiego polecenia: nazwa wyświetlana, którą użytkownicy wybierają z menu, aby wywołać polecenie. Może mieć maksymalnie 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ą: (science wersja przedpremierowa dla programistów) nazwa wyświetlana, którą użytkownicy wybierają z menu, aby wywołać działanie związane z wiadomością. Może mieć maksymalnie 50 znaków i zawierać znaki specjalne. Na przykład Remind me.

5. Opcjonalnie: Komunikat powiadomienia o wczytywaniu: (science wersja przedpremierowa dla programistów) komunikat powiadomienia w postaci wyskakującego okienka, który ma być wyświetlany użytkownikowi podczas wykonywania działania związanego z wiadomością. Dostępne tylko w przypadku działań związanych z wiadomością, które nie otwierają okien.

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

7. Kliknij Zapisz.

Polecenie jest teraz skonfigurowane dla aplikacji Google Chat.

Odpowiadanie na polecenie

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

Aby odpowiadać na poszczególne typy poleceń, musisz obsługiwać różne typy zdarzeń i obiekty metadanych w ładunku zdarzenia:

Więcej informacji o tym, jak odpowiadać na polecenie za pomocą wiadomości, znajdziesz w tych sekcjach.

Odpowiadanie na polecenie po ukośniku

Poniższy kod przedstawia przykład aplikacji Google Chat, która 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 wiadomość prywatną:

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

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

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 {}

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

Odpowiadanie na szybkie polecenie

Poniższy kod przedstawia przykład aplikacji Google Chat, 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ą:

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

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

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 {}

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

Odpowiadanie na działanie związane z wiadomością

Poniższy kod przedstawia przykład aplikacji Google Chat, która 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 wiadomość prywatną:

/**
 * 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}"`
    });
  }
}

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

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}"'
        }

/**
 * 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, który został określony podczas konfigurowania polecenia w konsoli Google Cloud.

Testowanie polecenia

Aby przetestować polecenie i kod, przeczytaj artykuł Testowanie funkcji interaktywnych aplikacji Google Chat.

Aby dowiedzieć się, jak testować i używać polecenia w interfejsie Google Chat, przeczytaj artykuł Korzystanie z aplikacji w Google Chat w dokumentacji Centrum pomocy Google Chat.

Powiązane artykuły

• Wyświetl przykłady aplikacji Google Chat które używają poleceń
• Wysyłanie wiadomości
• Otwieranie interaktywnych okien