Odpowiadanie na polecenia z ukośnikiem w Google Chat

Na tej stronie znajdziesz informacje o tym, jak skonfigurować aplikację Google Chat, aby reagowała na polecenia z użyciem znaku ukośnika.

W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat.

Polecenie po ukośniku to częsty sposób uruchamiania aplikacji Google Chat i wchodzenia z nią w interakcje. Polecenia po ukośniku pomagają też użytkownikom odkrywać i korzystać z kluczowych funkcji aplikacji. Aby zdecydować, czy chcesz skonfigurować polecenia po ukośniku, i zrozumieć, jak projektować interakcje z użytkownikiem, zapoznaj się z dokumentacją interfejsu API Google Chat Definiowanie wszystkich ścieżek użytkownika.

Jak użytkownicy korzystają z poleceń po ukośniku

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:

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

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:

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 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. W następującej sekcji musisz użyć tego skrótu, aby odpowiedzieć na polecenie.

4. W sekcji Polecenia kliknij Dodaj polecenie.

5. Wpisz identyfikator polecenia, typ polecenia, nazwę polecenia po ukośniku oraz nazwę i opis polecenia:

   1. 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.
   2. Typ polecenia: wybierz Polecenie po ukośniku.
   3. Nazwa polecenia rozpoczynająca się ukośnikiem: wyświetlana nazwa polecenia i sposób, w jaki użytkownicy mogą wywołać Twoją aplikację. Musi zaczynać się ukośnikiem, zawierać tylko tekst i mieć maksymalnie 50 znaków.
   4. Nazwa: przyjazna dla użytkownika nazwa polecenia. Nazwy mogą mieć maksymalnie 50 znaków i mogą zawierać znaki specjalne.
      • 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 polecenie Update contact (Zaktualizuj kontakt) służy do modyfikowania rekordu kontaktu.
   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 po ukośniku zostało skonfigurowane w aplikacji Google Chat.

Odpowiedź na polecenie po ukośniku

Gdy użytkownicy tworzą wiadomość w Google Chat, Twoja aplikacja Google Chat otrzymuje obiekt zdarzenia zawierający informacje o wiadomości. Obiekt zdarzenia zawiera ładunek AppCommand z informacjami o poleceniu użytym w wiadomości (w tym o identyfikatorze polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź.

Aby odpowiedzieć na polecenie po ukośniku, musisz zaimplementować polecenie aplikacji, aby aplikacja Google Chat mogła obsługiwać obiekty zdarzeń zawierające metadane polecenia aplikacji.

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:

// 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 APP_COMMAND events
    if (chatEvent.appCommandPayload) {

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

        if (appCommandMetadata.appCommandType === "SLASH_COMMAND") {
            // 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;

    if (appCommandMetadata.appCommandType == "SLASH_COMMAND") {

        // 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ł określony podczas konfigurowania polecenia z ukośnikiem w Google Chat API.