Odpowiadanie na polecenia po ukośniku jako aplikacja Google Chat

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

Polecenie po ukośniku to popularny sposób wywoływania aplikacji do obsługi czatu i interakcji z nią. Pozwalają one też użytkownikom odkrywać i korzystać z kluczowych funkcji aplikacji do obsługi czatu.

Aby użyć polecenia po ukośniku, użytkownicy wpisują ukośnik (/), a następnie krótkie polecenie tekstowe, na przykład /about, aby uzyskać informacje o aplikacji Chat. Użytkownicy mogą odkryć dostępne polecenia po ukośniku, wpisując ukośnik w Google Chat. Spowoduje to wyświetlenie okna z listą dostępnych poleceń w aplikacji Chat:

Ilustracja 1. Okno, które pojawia się, gdy użytkownicy wpisują znak ukośnika w Google Chat.

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

Polecenia po ukośniku z odpowiedziami prywatnymi

Gdy użytkownik wyśle wiadomość zawierającą polecenie po ukośniku, będzie ona widoczna tylko dla niego i aplikacji Google Chat. Jeśli aplikacja Google Chat została dodana do pokoju z wieloma osobami, możesz odpowiedzieć na polecenie po ukośniku prywatnie, aby zachować prywatność interakcji między użytkownikiem a aplikacją Google Chat.

Aby dowiedzieć się więcej o aplikacji Google Chat znalezionej w pokoju, użytkownicy mogą użyć poleceń takich jak /about lub /help. Aby uniknąć powiadamiania wszystkich innych osób w przestrzeni, aplikacja Google Chat może odpowiadać prywatnie, podając informacje o tym, jak korzystać z aplikacji Google Chat i uzyskać pomoc.

Wymagania wstępne

Uwaga: przykładowe fragmenty kodu w tym przewodniku zostały napisane tak, aby działały jako funkcje Google Cloud Functions w Node.js, Pythonie i Javie.

Node.js

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.

Google Apps Script

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

Python

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.

Java

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 po ukośniku

Z tej sekcji dowiesz się, jak skonfigurować polecenie /:

1. Utwórz nazwę polecenia po ukośniku.
2. Skonfiguruj polecenie po ukośniku w Google Chat API.

Nazwij polecenie po ukośniku

Nazwa polecenia po ukośniku to to, co użytkownicy wpisują w wiadomości w Google Chat, aby wywołać tę aplikację. Pod nazwą pojawia się też krótki opis, który informuje użytkowników, jak używać danego polecenia:

Rysunek 2. Nazwa i opis polecenia po ukośniku.

Wybierając nazwę i opis polecenia po ukośniku, weź pod uwagę te rekomendacje:

• Aby nadać nazwę poleceniu po ukośniku:

  • Używaj krótkich, opisowych i użytecznych słów lub wyrażeń, aby polecenia były jasne i proste dla użytkownika. Na przykład zamiast /createAReminder użyj /remindMe.
  • Jeśli polecenie składa się z więcej niż jednego słowa, ułatwij użytkownikom jego odczytanie, pisząc pierwsze słowo małymi literami, a pierwszą literę kolejnych słów – wielkimi. Na przykład zamiast /updatecontact użyj /updateContact.
  • Zastanów się, czy chcesz użyć niepowtarzalnej czy wspólnej nazwy polecenia. Jeśli polecenie opisuje typowe działanie lub funkcję, możesz użyć powszechnej nazwy, którą użytkownicy rozpoznają i oczekują, np. /settings lub /feedback. W przeciwnym razie używaj unikalnych nazw poleceń, ponieważ jeśli nazwa Twojego polecenia jest taka sama jak w innych aplikacjach do czatu, użytkownik musi przefiltrować podobne polecenia, aby znaleźć i użyć Twojego.

• Aby opisać polecenie po ukośniku:

  • Opis powinien być krótki i jasny, aby użytkownicy wiedzieli, czego się spodziewać po wywołaniu polecenia.
  • Poinformuj użytkowników, czy polecenie ma jakieś wymagania dotyczące formatowania. Jeśli np. utworzysz polecenie /remindMe, które wymaga argumentu tekst, ustaw opis na coś takiego jak Remind me to do [something] at [time].
  • Poinformuj użytkowników, czy aplikacja Google Chat ma odpowiadać wszystkim w pokoju, czy tylko użytkownikowi, który wywołał polecenie. Na przykład w przypadku polecenia z ukośnikiem /about możesz je opisać jako Learn about this app (Only visible to you).

Konfigurowanie polecenia po ukośniku w Google Chat API

Aby utworzyć polecenie z ukośnikiem, musisz podać informacje o tym poleceniu w konfiguracji aplikacji Google Chat dla interfejsu Google Chat API.

Aby skonfigurować polecenie z ukośnikiem w interfejsie 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 po ukośniku kliknij Dodaj polecenie po ukośniku.

4. Wpisz nazwę, identyfikator i opis polecenia:

   1. Nazwa: wyświetlana nazwa polecenia i tekst, który użytkownicy wpisują, aby wywołać aplikację. Musi zaczynać się ukośnikiem, zawierać tylko tekst i mieć maksymalnie 50 znaków.
   2. Opis: tekst opisujący sposób użycia i sformatowania polecenia. Opis może mieć maksymalnie 50 znaków.
   3. Identyfikator polecenia: liczba z zakresu od 1 do 1000, której używa aplikacja Google Chat do rozpoznawania polecenia po ukośniku i zwracania odpowiedzi.

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 po ukośniku zostało skonfigurowane w aplikacji Google Chat.

Odpowiedź na polecenie po ukośniku

Więcej przykładów znajdziesz w próbnych wersjach aplikacji Google Chat.

Gdy użytkownicy tworzą wiadomość na czacie zawierającą polecenie po ukośniku, Twoja aplikacja do obsługi czatu otrzymuje zdarzenie interakcji MESSAGE. Ładunek zdarzeń zawiera obiekty slashCommand i slashCommandMetadata. Te obiekty zawierają szczegóły polecenia użytego w wiadomości (w tym identyfikator polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź.

Aplikacja Google Chat odpowiada prywatnie na komendę /help, aby wyjaśnić, jak uzyskać pomoc.

Poniższy kod pokazuje przykład aplikacji Google Chat, która odpowiada na polecenie /about za pomocą obsługi zdarzeń interakcji MESSAGE i wykrywania, czy wiadomość zawiera pasujące identyfikatory poleceń. Jeśli wiadomość zawiera identyfikator polecenia, aplikacja Google Chat zwróci 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;
  }
}

Ustaw ABOUT_COMMAND_ID na identyfikator polecenia określony podczas konfigurowania polecenia po ukośniku w Chat API. Aby przetestować ten kod, zapoznaj się z artykułem Testowanie interaktywnych funkcji aplikacji Google Chat.

Powiązane artykuły

• Zobacz przykłady aplikacji Google Chat, które używają poleceń po ukośniku
• Wyślij wiadomość
• Wysyłanie wiadomości prywatnych
• Otwieranie interaktywnych dialogów