Odpowiadanie na polecenia aplikacji Google Chat

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

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

Wymagania wstępne

HTTP Google 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 zalecenia:

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 unikalnej 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 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 je opisać jako 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 interfejsu Google Chat API w aplikacji Google Chat.

Aby skonfigurować polecenie w interfejsie Google Chat API, wykonaj te czynności: aby skonfigurować polecenie z pochylnią 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 zaawansowane otwórz Wyzwalacze i sprawdź, czy pole Polecenie aplikacji zawiera odpowiedni wyzwalacz, np. punkt końcowy HTTP lub funkcję Apps Script. Aby odpowiedzieć na to polecenie, musisz użyć tego okna w sekcji poniżej.

  4. W sekcji Polecenia kliknij Dodaj polecenie.

  5. Podaj te informacje o komandze:

    1. Identyfikator polecenia: liczba z zakresu 1–1000, której używa aplikacja Google Chat do rozpoznawania polecenia i zwracania odpowiedzi.
    2. Typ polecenia: wybierz Szybkie polecenie lub Polecenie po ukośniku.
    3. Jeśli konfigurujesz polecenie po ukośniku, wpisz wartość w polu Nazwa polecenia po ukośniku, aby określić, co użytkownicy muszą wpisać, aby wywołać to polecenie. Musi zaczynać się od ukośnika, zawierać tylko tekst i mieć maksymalnie 50 znaków. Na przykład: /remindMe.
    4. Nazwa: przyjazna dla użytkownika nazwa polecenia. Nazwy mogą mieć maksymalnie 50 znaków i mogą zawierać znaki specjalne.
    5. Opis: tekst opisujący sposób użycia i sformatowania polecenia. Opis może mieć maksymalnie 50 znaków.

  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 do funkcji Apps Script określonej podczas konfigurowania okna 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 /about za pomocą wiadomości tekstowej. 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 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;

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

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