Odpowiadanie na polecenia aplikacji Google Chat

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

Polecenia pomagają użytkownikom odkrywać i używać najważniejszych funkcji aplikacji Google Chat. Tylko aplikacje Google Chat mogą wyświetlać zawartość polecenia. Jeśli na przykład użytkownik wyśle wiadomość z poleceniem po ukośniku, będzie ona widoczna tylko dla niego i aplikacji Google Chat.

Aby zdecydować, czy warto tworzyć polecenia, i dowiedzieć się, jak projektować interakcje z użytkownikami, przeczytaj artykuł Określanie wszystkich ścieżek użytkownika.

Typy poleceń aplikacji Google Chat

1. Polecenia po ukośniku: użytkownicy mogą wybrać polecenie po ukośniku z menu lub wpisać ukośnik (/), a następnie predefiniowany tekst, np. /about. Aplikacje Google Chat zwykle wymagają tekstu argumentu dla polecenia po ukośniku.

   Utwórz polecenie po ukośniku, jeśli aplikacja Google Chat wymaga dodatkowych danych wejściowych od użytkownika. Możesz na przykład utworzyć polecenie po ukośniku o nazwie /search które zostanie uruchomione, gdy użytkownik wpisze frazę do wyszukania, np. /search receipts.

2. Szybkie polecenia: użytkownicy używają poleceń, otwierając menu w obszarze odpowiedzi na wiadomość w Google Chat. Aby użyć polecenia, klikają Dodaj i wybierają polecenie z menu.

   Utwórz szybkie polecenie, jeśli aplikacja Google Chat może natychmiast odpowiedzieć użytkownikowi bez czekania na dodatkowe dane wejściowe. Możesz na przykład utworzyć szybkie polecenie o nazwie Losowy obraz, które natychmiast odpowiada obrazem.

3. Działania związane z wiadomościami: (science wersja zapoznawcza dla programistów) użytkownicy używają działań związanych z wiadomościami, najeżdżając kursorem na wiadomość i klikając menu z 3 kropkami. Aby użyć polecenia, otwierają menu z 3 kropkami i wybierają polecenie z menu.

   Utwórz działanie związane z wiadomościami, jeśli aplikacja Google Chat może wykonywać działania na podstawie na podstawie kontekstu wiadomości.

Na ilustracjach poniżej pokazano, jak użytkownicy odkrywają menu poleceń po ukośniku i szybkich poleceń oraz działań związanych z wiadomościami:

Wymagania wstępne

Konfigurowanie polecenia

W tej sekcji dowiesz się, jak wykonać te czynności, aby skonfigurować polecenie:

1. Utwórz nazwę i opis polecenia.
2. Skonfiguruj polecenie w konsoli Google Cloud.

Nadawanie nazwy i opisywanie polecenia

Nazwa polecenia to tekst, który użytkownicy wpisują lub wybierają, aby wywołać aplikację Google Chat. Krótki opis pojawia się też pod nazwą, aby dodatkowo zachęcić użytkowników do korzystania z polecenia:

Podczas wybierania nazwy i opisu polecenia weź pod uwagę te zalecenia:

Aby nazwać polecenie:

• Używaj krótkich, opisowych i zachęcających do działania słów lub fraz, aby polecenia były jasne dla użytkownika. Zamiast nazwy Create a reminder użyj na przykład Remind me.
• Rozważ użycie unikalnej lub popularnej nazwy polecenia. Jeśli polecenie opisuje typową interakcję lub funkcję, możesz użyć popularnej nazwy, którą użytkownicy rozpoznają i której się spodziewają, np. Settings lub Feedback. W przeciwnym razie spróbuj użyć unikalnych nazw poleceń, ponieważ jeśli nazwa polecenia jest taka sama jak w przypadku innych aplikacji Google Chat, użytkownik musi filtrować podobne polecenia, aby znaleźć i użyć Twojego.

Aby opisać polecenie:

• Opis powinien być krótki i jasny, aby użytkownicy wiedzieli, czego się spodziewać, gdy użyją 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 tekstu argumentu, ustaw opis na coś takiego jak Remind me to do [something] at [time].
• Poinformuj użytkowników, czy aplikacja Google Chat odpowiada wszystkim w pokoju, czy prywatnie 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, szybkie polecenie lub działanie związane z wiadomościami, musisz określić informacje o poleceniu lub działaniu w konfiguracji aplikacji Google Chat dla interfejsu Google Chat API.

Aby skonfigurować polecenie 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 > Google Chat API

   Otwórz stronę Google Chat API

2. Kliknij Konfiguracja.

3. W sekcji Ustawienia połączenia otwórz Wyzwalacze i określ szczegóły punktu końcowego. Aby odpowiedzieć na polecenie, musisz użyć tego wyzwalacza w następnej sekcji.

   1. URL punktu końcowego HTTP: możesz tu określić jeden wspólny URL punktu końcowego HTTP tutaj. Możesz też użyć różnych punktów końcowych HTTP dla różnych wyzwalaczy, określając 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, określ nazwę funkcji niestandardowej w polu Polecenie aplikacji.

4. W sekcji Polecenia kliknij Dodaj polecenie.

5. Wpisz te informacje o poleceniu:

   1. Identyfikator polecenia: liczba od 1 do 1000, której aplikacja Google Chat używa do rozpoznawania polecenia i zwracania odpowiedzi.
   2. Opis: tekst opisujący, jak używać i formatować polecenie. Opisy mogą mieć maksymalnie 50 znaków.
   3. Typ polecenia: wybierz Szybkie polecenie, Polecenie po ukośniku lub Działanie związane z wiadomościami.
   4. Określ nazwę polecenia:
      • Nazwa szybkiego polecenia: nazwa wyświetlana, którą użytkownicy wybierają z menu, aby wywołać polecenie. Może mieć maksymalnie 50 znaków i zawierać 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.
      • Nazwa działania związanego z wiadomościami: (science wersja zapoznawcza dla programistów) nazwa wyświetlana, którą użytkownicy wybierają z menu, aby wywołać działanie związane z wiadomościami. Może mieć maksymalnie 50 znaków i zawierać znaki specjalne. Na przykład Remind me.

6. Opcjonalnie: Komunikat powiadomienia o wczytywaniu: (science wersja zapoznawcza dla programistów) komunikat powiadomienia typu toast, który ma być wyświetlany użytkownikowi podczas wykonywania działania związanego z wiadomościami. Dostępne tylko w przypadku działań związanych z wiadomościami, które nie otwierają okien.

7. Opcjonalnie: jeśli chcesz, aby aplikacja Google Chat odpowiadała na polecenie za pomocą okna, zaznacz pole Otwórz okno.

8. Kliknij Zapisz.

Polecenie jest teraz skonfigurowane dla aplikacji Google Chat.

Odpowiadanie na polecenie

Gdy użytkownicy używają polecenia, aplikacja Google Chat otrzymuje obiekt zdarzenia. Ładunek zdarzenia zawiera obiekt appCommandPayload ze szczegółami wywołanego polecenia (w tym identyfikatorem i typem polecenia), dzięki czemu możesz zwrócić odpowiednią odpowiedź. Obiekt zdarzenia jest wysyłany do punktu końcowego HTTP lub funkcji Apps Script , które zostały określone podczas konfigurowania wyzwalacza Polecenie aplikacji.

Poniższy kod przedstawia przykład aplikacji Google Chat która odpowiada na polecenie po ukośniku /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 identyfikator polecenia po ukośniku, aplikacja Google Chat zwraca działanie DataActions z obiektem createMessageAction:

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Handle requests from Google Workspace add on
 *
 * @param {Object} req Request sent by Google Chat
 * @param {Object} res Response to be sent back to Google Chat
 */
http('avatarApp', (req, res) => {
  const chatEvent = req.body.chat;
  let message;
  if (chatEvent.appCommandPayload) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: {
    message: message
  }}}});
});

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 * @return the response message object.
 */
function handleAppCommand(event) {
  switch (event.appCommandPayload.appCommandMetadata.appCommandId) {
    case ABOUT_COMMAND_ID:
      return {
        text: 'The Avatar app replies to Google Chat messages.'
      };
  }
}

# The ID of the slash command "/about".
# You must use the same ID in the Google Chat API configuration.
ABOUT_COMMAND_ID = 1

@functions_framework.http
def avatar_app(req: flask.Request) -> Mapping[str, Any]:
  """Handle requests from Google Workspace add on

  Args:
    flask.Request req: the request sent by Google Chat

  Returns:
    Mapping[str, Any]: the response to be sent back to Google Chat
  """
  chat_event = req.get_json(silent=True)["chat"]
  if chat_event and "appCommandPayload" in chat_event:
    message = handle_app_command(chat_event)
  else:
    message = handle_message(chat_event)
  return { "hostAppDataAction": { "chatDataAction": { "createMessageAction": {
      "message": message
  }}}}

def handle_app_command(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Responds to an APP_COMMAND event in Google Chat.

  Args:
    Mapping[str, Any] event: the event object from Google Chat

  Returns:
    Mapping[str, Any]: the response message object.
  """
  if event["appCommandPayload"]["appCommandMetadata"]["appCommandId"] == ABOUT_COMMAND_ID:
    return {
      "text": "The Avatar app replies to Google Chat messages.",
    }
  return {}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
private static final int ABOUT_COMMAND_ID = 1;

private static final Gson gson = new Gson();

/**
 * Handle requests from Google Workspace add on
 * 
 * @param request the request sent by Google Chat
 * @param response the response to be sent back to Google Chat
 */
@Override
public void service(HttpRequest request, HttpResponse response) throws Exception {
  JsonObject event = gson.fromJson(request.getReader(), JsonObject.class);
  JsonObject chatEvent = event.getAsJsonObject("chat");
  Message message;
  if (chatEvent.has("appCommandPayload")) {
    message = handleAppCommand(chatEvent);
  } else {
    message = handleMessage(chatEvent);
  }
  JsonObject createMessageAction = new JsonObject();
  createMessageAction.add("message", gson.fromJson(gson.toJson(message), JsonObject.class));
  JsonObject chatDataAction = new JsonObject();
  chatDataAction.add("createMessageAction", createMessageAction);
  JsonObject hostAppDataAction = new JsonObject();
  hostAppDataAction.add("chatDataAction", chatDataAction);
  JsonObject dataActions = new JsonObject();
  dataActions.add("hostAppDataAction", hostAppDataAction);
  response.getWriter().write(gson.toJson(dataActions));
}

/**
 * Handles an APP_COMMAND event in Google Chat.
 *
 * @param event the event object from Google Chat
 * @return the response message object.
 */
private Message handleAppCommand(JsonObject event) throws Exception {
  switch (event.getAsJsonObject("appCommandPayload")
    .getAsJsonObject("appCommandMetadata").get("appCommandId").getAsInt()) {
    case ABOUT_COMMAND_ID:
      return new Message()
        .setText("The Avatar app replies to Google Chat messages.");
    default:
      return null;
  }
}

// The ID of the slash command "/about".
// You must use the same ID in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 1;

/**
 * Responds to an APP_COMMAND event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onAppCommand(event) {
  // Executes the app command logic based on ID.
  switch (event.chat.appCommandPayload.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 określonym podczas konfigurowania polecenia w interfejsie Chat API.

Odpowiadanie na działanie związane z wiadomościami

Poniższy kod przedstawia przykład aplikacji Google Chat, która odpowiada na działanie związane z wiadomościami Przypomnij mi wiadomością tekstową. Aby odpowiadać na działania związane z wiadomościami, aplikacja Google Chat obsługuje obiekty zdarzeń z wyzwalacza Polecenie aplikacji. Gdy ładunek obiektu zdarzenia zawiera identyfikator polecenia działania związanego z wiadomościami, aplikacja Google Chat zwraca działanie DataActions z obiektem createMessageAction:

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @param {Object} res The HTTP response object.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event, res) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return res.json({
      "hostAppDataAction": {
        "chatDataAction": {
          "createMessageAction": {
            "message": {
              "text": `Setting a reminder for message: "${messageText}"`
            }
          }
        }
      }
    });
  }
}

def on_app_command(event):
    """Responds to an APP_COMMAND interaction event from Google Chat.

    Args:
        event (dict): The interaction event from Google Chat.

    Returns:
        dict: The JSON response message with a confirmation.
    """
    # Collect the command ID and type from the event metadata.
    payload = event.get('chat', {}).get('appCommandPayload', {})
    metadata = payload.get('appCommandMetadata', {})
    if metadata.get('appCommandType') == 'MESSAGE_ACTION' and \
       metadata.get('appCommandId') == REMIND_ME_COMMAND_ID:

        # Message actions can access the context of the message they were
        # invoked on, such as the text or sender of that message.
        message_text = payload.get('message', {}).get('text')

        # Return a response that includes details from the original message.
        return {
            "hostAppDataAction": {
                "chatDataAction": {
                    "createMessageAction": {
                        "message": {
                            "text": f'Setting a reminder for message: "{message_text}"'
                        }
                    }
                }
            }
        }

/**
 * Responds to an APP_COMMAND interaction event from Google Chat.
 *
 * @param event The interaction event from Google Chat.
 * @param response The HTTP response object.
 */
void onAppCommand(JsonObject event, HttpResponse response) throws Exception {
  // Collect the command ID and type from the event metadata.
  JsonObject payload = event.getAsJsonObject("chat").getAsJsonObject("appCommandPayload");
  JsonObject metadata = payload.getAsJsonObject("appCommandMetadata");
  String appCommandType = metadata.get("appCommandType").getAsString();

  if (appCommandType.equals("MESSAGE_ACTION")) {
    int commandId = metadata.get("appCommandId").getAsInt();
    if (commandId == REMIND_ME_COMMAND_ID) {
      // Message actions can access the context of the message they were
      // invoked on, such as the text or sender of that message.
      String messageText = payload.getAsJsonObject("message").get("text").getAsString();

      // Return a response that includes details from the original message.
      JsonObject responseMessage = new JsonObject();
      responseMessage.addProperty("text", "Setting a reminder for message: " + messageText);

      JsonObject createMessageAction = new JsonObject();
      createMessageAction.add("message", responseMessage);

      JsonObject chatDataAction = new JsonObject();
      chatDataAction.add("createMessageAction", createMessageAction);

      JsonObject hostAppDataAction = new JsonObject();
      hostAppDataAction.add("chatDataAction", chatDataAction);

      JsonObject finalResponse = new JsonObject();
      finalResponse.add("hostAppDataAction", hostAppDataAction);

      response.getWriter().write(finalResponse.toString());
    }
  }
}

/**
 * Responds to an APP_COMMAND interaction event in Google Chat.
 *
 * @param {Object} event The interaction event from Google Chat.
 * @return {Object} The JSON response message with a confirmation.
 */
function onAppCommand(event) {
  // Collect the command ID and type from the event metadata.
  const {appCommandId, appCommandType} =
    event.chat.appCommandPayload.appCommandMetadata;

  if (appCommandType === 'MESSAGE_ACTION' &&
      appCommandId === REMIND_ME_COMMAND_ID) {

    // Message actions can access the context of the message they were
    // invoked on, such as the text or sender of that message.
    const messageText = event.chat.appCommandPayload.message.text;

    // Return a response that includes details from the original message.
    return CardService.newChatResponseBuilder()
        .setText("Setting a reminder for message: " + messageText)
        .build();
  }
}

Aby użyć tego przykładowego kodu, zastąp REMIND_ME_COMMAND_ID identyfikatorem polecenia określonym podczas konfigurowania polecenia w interfejsie Chat API.

Testowanie polecenia

Aby przetestować polecenie i kod, przeczytaj artykuł Testowanie funkcji interaktywnych aplikacji Google Chat.

Aby dowiedzieć się, jak testować i używać polecenia w interfejsie Google Chat, przeczytaj artykuł Korzystanie z aplikacji w Google Chat w dokumentacji Centrum pomocy Google Chat.

Powiązane artykuły

• Wyświetlanie przykładów aplikacji Google Chat które używają poleceń
• Wysyłanie wiadomości
• Otwieranie interaktywnych okien