Odpowiadanie na polecenia aplikacji Google Chat

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

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 po ukośniku: użytkownicy wysyłają polecenia w postaci wiadomości, wpisując ukośnik (/), a następnie wstępnie zdefiniowany 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 w obszarze odpowiedzi ukośnik /, a następnie nazwę polecenia.
  • Użytkownik wyświetla szybkie polecenia w menu.
    Rysunek 2. Użytkownicy mogą odkrywać i używać szybkich poleceń z menu w obszarze odpowiedzi na wiadomość w Google Chat.

Wymagania wstępne

HTTP

Dodatek do Google Workspace, który rozszerza Google Chat. Aby utworzyć taki plik, wykonaj wprowadzenie do HTTP.

Google Apps Script

Dodatek do Google Workspace, który rozszerza Google Chat. Aby utworzyć skrypt, zapoznaj się z krótkim przewodnikiem po Apps Script.

Konfigurowanie polecenia

W tej sekcji opisaliśmy, jak skonfigurować polecenie, wykonując te czynności:

  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 rekomendacje:

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 niepowtarzalnej 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 danego 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 użyć opisu 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 aplikacji Chat dla interfejsu Google Chat API.

Aby skonfigurować polecenie w interfejsie Google Chat API, wykonaj te czynności: aby skonfigurować polecenie z pochylonym znakiem kreski 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 Ustawienia połączenia kliknij Aktywatory i podaj szczegóły punktu końcowego. Aby odpowiedzieć na to polecenie, musisz użyć tego okna w następującej sekcji.

    1. URL punktu końcowego HTTP: możesz tutaj podać jeden wspólny adres URL punktu końcowego HTTP. Aby używać różnych punktów końcowych HTTP w przypadku różnych aktywatorów, możesz też podać punkt końcowy bezpośrednio w polu Polecenie aplikacji.
    2. Apps Script: wpisz identyfikator wdrożenia Apps Script. Domyślnie zostanie wywołana funkcja onAppCommand. Aby użyć innej funkcji Apps Script, w polu Polecenie aplikacji wpisz nazwę funkcji niestandardowej.

  4. W sekcji Polecenia kliknij Dodaj polecenie.

  5. Podaj te informacje o komendzie:

    1. Identyfikator polecenia: liczba z zakresu 1–1000, której używa aplikacja Google Chat do rozpoznawania polecenia i zwracania odpowiedzi.
    2. Opis: tekst opisujący sposób użycia i sformatowania polecenia. Opis może zawierać maksymalnie 50 znaków.
    3. Typ polecenia: wybierz Szybkie polecenie lub Polecenie po ukośniku.
    4. Podaj nazwę szybkiego polecenia lub polecenia po ukośniku:
      • Nazwa szybkiego polecenia: wyświetlana nazwa, którą użytkownicy wybierają w 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 mieć maksymalnie 50 znaków. Na przykład: /remindMe.

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

  7. Kliknij Zapisz.

Polecenie zostało skonfigurowane w aplikacji Google Chat.

Odpowiedź na polecenie

Gdy użytkownicy używają polecenia, aplikacja Google Chat otrzymuje obiekt zdarzenia. Ładunek wydarzenia zawiera obiekt appCommandPayload z informacjami o wywołanym poleceniu (w tym identyfikator i typ polecenia), aby umożliwić zwrócenie odpowiedniej odpowiedzi. Obiekt zdarzenia jest wysyłany do punktu końcowego HTTP lub funkcji Apps Script określonej podczas konfigurowania aktywatora polecenia aplikacji.

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 z cudzysłowem /about wiadomością tekstową. Aby odpowiadać na polecenia po ukośniku, aplikacja Google Chat obsługuje obiekty zdarzeń z wyzwalacza Polecenie aplikacji. Gdy ładunek obiektu zdarzenia zawiera znak slash (/) i identyfikator polecenia, aplikacja do czatu zwraca działanie DataActions z obiektem createMessageAction:

Node.js 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Google Cloud Function that responds to events sent from a
 * Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.avatarApp = function avatarApp(req, res) {
    if (req.method === 'GET' || !req.body.chat) {
        return res.send('Hello! This function is meant to be used ' +
            'in a Google Chat Space.');
    }
    // Stores the Google Chat event as a variable.
    const chatEvent = req.body.chat;

    // Handles events that contain payloads about commands
    if (chatEvent.appCommandPayload) {

      // Stores the Google Chat app command metadata as a variable.
      const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;

      // Executes the slash command logic based on its ID.
      // Slash command IDs are set in the Google Chat API configuration.
      switch (appCommandMetadata.appCommandId) {
          case ABOUT_COMMAND_ID:
              return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
                  text: 'The Avatar app replies to Google Chat messages.'
              }}}}});
      }
    // Handles MESSAGE events
    } else if (chatEvent.messagePayload) {

        // Stores the Google Chat event as a variable.
        const chatMessage = chatEvent.messagePayload.message;

        // Replies with the sender's avatar in a card otherwise.
        const displayName = chatMessage.sender.displayName;
        const avatarUrl = chatMessage.sender.avatarUrl;
        res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
            text: 'Here\'s your avatar',
            cardsV2: [{
                cardId: 'avatarCard',
                card: {
                    name: 'Avatar Card',
                    header: {
                        title: `Hello ${displayName}!`,
                    },
                    sections: [{
                        widgets: [{
                            textParagraph: { text: 'Your avatar picture: ' }
                        }, {
                            image: { imageUrl: avatarUrl }
                        }]
                    }]
                }
            }]
        }}}}});
    }
};

Google Apps Script 

// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;

/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {

    // Stores the Google Chat event as a variable.
    const chatMessage = event.chat.messagePayload.message;

    // Replies with the sender's avatar in a card otherwise.
    const displayName = chatMessage.sender.displayName;
    const avatarUrl = chatMessage.sender.avatarUrl;
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
        text: 'Here\'s your avatar',
        cardsV2: [{
            cardId: 'avatarCard',
            card: {
                name: 'Avatar Card',
                header: {
                    title: `Hello ${displayName}!`,
                },
                sections: [{
                    widgets: [{
                        textParagraph: { text: 'Your avatar picture: ' }
                    }, {
                        image: { imageUrl: avatarUrl }
                    }]
                }]
            }
        }]
    }}}}};
}

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {

  // Stores the Google Chat app command metadata as a variable.
  const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;

  // Executes the slash command logic based on its ID.
  // Slash command IDs are set in the Google Chat API configuration.
  switch (appCommandMetadata.appCommandId) {
      case ABOUT_COMMAND_ID:
          return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
              text: 'The Avatar app replies to Google Chat messages.'
          }}}}};
  }
}

Aby użyć tego przykładowego kodu, zastąp ABOUT_COMMAND_ID identyfikatorem polecenia, który został podany podczas konfigurowania polecenia w Google Chat API.

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.