Odpowiadanie na polecenia po ukośniku jako aplikacja Google Chat

Z tego artykułu dowiesz się, jak skonfigurować polecenia po ukośniku w aplikacji Google Chat i reagować na nie.

Polecenie ukośnika jest typowym sposobem wywoływania aplikacji przez użytkowników i interakcji z nią. Polecenia po ukośniku ułatwiają też użytkownikom odkrywanie i korzystanie z najważniejszych 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, takie jak /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:

Okno polecenia po ukośniku
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 na przykład 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

Node.js

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację do obsługi czatu przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Google Apps Script

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. 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ę do obsługi czatu przy użyciu 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 przy użyciu usługi HTTP, wykonaj to krótkie wprowadzenie.

Skonfiguruj polecenie po ukośniku

W tej sekcji opisaliśmy, jak skonfigurować polecenie z pochylonym znakiem kreski:

  1. Utwórz nazwę polecenia po ukośniku.
  2. Skonfiguruj polecenie po ukośniku w interfejsie 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:

Nazwa i opis polecenia po ukośniku
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 praktycznych słów lub wyrażeń, aby polecenia były zrozumiałe 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 użyć niepowtarzalnej czy wspólnej nazwy polecenia. Jeśli polecenie opisuje typową interakcję 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 zrozumiały, 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 na przykład utworzysz polecenie /remindMe, które wymaga tekstu argumentu, ustaw opis na podobny do 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).

Skonfiguruj polecenie po ukośniku w interfejsie Google Chat API

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

Aby skonfigurować polecenie z ukośnikiem 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 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

Gdy użytkownicy tworzą wiadomość na czacie zawierającą polecenie po ukośniku, Twoja aplikacja do obsługi czatu otrzymuje zdarzenie interakcji MESSAGE. Ładunek zdarzenia 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ź.

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.

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
// 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 res.send({
        privateMessageViewer: event.user,
        text: 'The Avatar app replies to Google Chat messages.'
      });
  }
}

Google Apps Script

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

python/avatar-app/main.py
# Checks for the presence of a slash command in the message.
if "slashCommand" in request_json["message"]:
  # Executes the slash command logic based on its ID.
  # Slash command IDs are set in the Google Chat API configuration.
  if request_json["message"]["slashCommand"]["commandId"] == ABOUT_COMMAND_ID:
    return {
      "privateMessageViewer": request_json["user"],
      "text": 'The Avatar app replies to Google Chat messages.'
    }

Java

java/avatar-app/src/main/java/App.java
// Checks for the presence of a slash command in the message.
if (body.getAsJsonObject("message").has("slashCommand")) {
  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  JsonObject slashCommand = body.getAsJsonObject("message").getAsJsonObject("slashCommand");
  switch (slashCommand.get("commandId").getAsString()) {
    case ABOUT_COMMAND_ID:
      Message aboutMessage = new Message();
      aboutMessage.setText("The Avatar app replies to Google Chat messages.");
      aboutMessage.setPrivateMessageViewer(new User()
        .setName(body.getAsJsonObject("user").get("name").getAsString()));
      response.getWriter().write(gson.toJson(aboutMessage));
      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.