Otrzymuj interakcje użytkowników i reaguj na nie

Na tej stronie opisujemy, jak aplikacja Google Chat może odbierać interakcje użytkowników w Google Chat i na nie odpowiadać.

Aby utworzyć interaktywne interfejsy aplikacji Google Chat, użyj tych komponentów:

  • Aktywatory: sposoby, w jakie użytkownicy Google Chat mogą wywołać aplikację Google Chat, np. dodając ją do pokoju lub wysyłając do niej wiadomość.
  • Obiekty zdarzeń: dane, które aplikacje Google Chat otrzymują z aktywatorów lub interakcji z interfejsem.
  • Działania: sposoby, w jakie aplikacje Google Chat mogą reagować na interakcje, np. wysyłanie wiadomości lub zwracanie interfejsu opartego na kartach.
Aplikacja do Google Chat otrzymuje obiekt zdarzenia z aktywatora Dodano do pokoju
Ilustracja 1. Gdy użytkownik dodaje aplikację Google Chat do pokoju, aktywuje się aktywator Dodano do pokoju i wysyła obiekt zdarzenia. Aby odpowiedzieć wiadomością, aplikacja Google Chat obsługuje obiekt zdarzenia i zwraca działanie, które tworzy wiadomość.

Aplikacje do Google Chat mogą tworzyć i wyświetlać interfejsy na te sposoby:

  • Wiadomości, które mogą zawierać tekst, karty statyczne lub interaktywne oraz przyciski dodatkowe.
  • Strony główne (strona główna aplikacji), które pojawiają się na karcie Strona główna w czatach indywidualnych z aplikacją Google Chat.
  • Okna, czyli karty, które otwierają się w nowym oknie i zwykle proszą użytkowników o przesłanie informacji.
  • Podglądy linków, czyli karty z podglądem informacji o usłudze zewnętrznej.

Wymagania wstępne

Jak działają interakcje użytkowników

Gdy użytkownik wchodzi w interakcję z aplikacją Google Chat, Google Chat wywołuje skonfigurowany regułę i wysyła obiekt zdarzenia do punktu końcowego lub funkcji aplikacji Google Chat. Aplikacja do Google Chat przetwarza obiekt zdarzenia i może synchronicznie zwrócić działanie w ciągu 30 sekund lub odpowiedzieć asynchronicznie za pomocą interfejsu Chat API.

Ten diagram pokazuje, jak aplikacje Google Chat przetwarzają interakcje użytkowników i na nie odpowiadają:

Architektura przetwarzania interakcji użytkowników przez aplikacje Google Chat.

Aktywatory

Aktywatory to konkretne sposoby, w jakie użytkownicy wywołują aplikację do Google Chat za pomocą interfejsu Google Chat, np. za pomocą @wzmianek lub poleceń aplikacji.

W tabeli poniżej znajdziesz aktywatory Google Chat, ich opisy i typowe reakcje aplikacji do Google Chat:

Aktywator Opis Typowa odpowiedź
Dodano do pokoju

Użytkownik dodaje aplikację Google Chat do pokoju lub administrator Google Workspace instaluje aplikację Google Chat w pokojach czatu dla użytkowników w organizacji. Informacje o aplikacjach do Google Chat zainstalowanych przez administratorów znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie w dokumentacji pomocy dla administratorów Google Workspace.

Aplikacja do Google Chat wysyła wiadomość powitalną, która wyjaśnia, co robi aplikacja i jak użytkownicy w pokoju mogą z nią wchodzić w interakcje.
Wiadomość

Użytkownik wchodzi w interakcję z aplikacją Google Chat w wiadomości na jeden z tych sposobów:

  • Wysyła wiadomość w pokoju czatu z aplikacją Google Chat.
  • @wzmiankuje aplikację do Google Chat w dowolnym pokoju.
  • wysyła wiadomość zawierającą link, który pasuje do wzorca adresu URL podglądu linków;
  • Wpisuje tekst w menu wielokrotnego wyboru widżetu selectionInput.
Aplikacja do Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja do Google Chat odpowiada wiadomością, dołącza kartę podglądu linku lub sugeruje elementy w menu wielokrotnego wyboru.
Usunięto z pokoju

Użytkownik usuwa aplikację Google Chat z pokoju lub administrator Google Workspace odinstalowuje aplikację Google Chat dla użytkownika w organizacji.

Użytkownicy nie mogą usuwać aplikacji Google Chat zainstalowanych przez administratora. Jeśli użytkownik zainstalował wcześniej aplikację do Google Chat, pozostanie ona zainstalowana niezależnie od tego, czy administrator Google Workspace spróbuje ją odinstalować.

Aplikacja Google Chat usuwa wszystkie powiadomienia przychodzące skonfigurowane dla pokoju (np. usuwa webhook) i czyści pamięć wewnętrzną. Aplikacje do Google Chat nie mogą odpowiadać wiadomościami na ten aktywator, ponieważ nie są już członkami pokoju.
Polecenie aplikacji

Użytkownik wywołuje polecenie aplikacji Google Chat (np. polecenie po ukośniku, szybkie polecenie lub działanie na wiadomości).

Aplikacja do Google Chat odpowie na polecenie. Może na przykład odpowiedzieć wiadomością lub otworzyć okno.
Strona główna aplikacji

Użytkownik otwiera kartę Strona główna w czacie indywidualnym w aplikacji Google Chat lub wchodzi w interakcję z widżetem na karcie strony głównej.

Aplikacja do obsługi czatu zwraca obiekt RenderActions, który przesyła kartę strony głównej (pushCard) lub aktualizuje wyświetlaną kartę strony głównej (updateCard).

Punkty końcowe lub funkcje wywołania zwrotnego dla tych aktywatorów konfigurujesz w konsoli Google Cloud na stronie Konfiguracja interfejsu Chat API. Szczegółowe instrukcje znajdziesz w artykule Konfigurowanie interfejsu Google Chat API.

Konfigurowanie promptów początkowych

Prompty początkowe pomagają użytkownikom odkrywać funkcje aplikacji do Google Chat, gdy otwierają pusty czat indywidualny z aplikacją. Możesz skonfigurować maksymalnie 3 prompty początkowe.

Aby dodać i skonfigurować prompty rozpoczynające:

  1. W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API:

    Otwórz stronę konfiguracji interfejsu Chat API

  2. W sekcji Funkcje interaktywne znajdź Prompty początkowe i kliknij Dodaj domyślny prompt lub polecenie.

  3. W polu Pozycja (1–3) wpisz liczbę od 1 do 3, aby określić kolejność wyświetlania. Każdy skonfigurowany prompt musi mieć unikalną pozycję.

  4. W sekcji Wybór typu określ, jak ma się zachowywać prośba:

    • Prompt tekstowy: wypełnia pasek tworzenia wiadomości wstępnie zdefiniowanym tekstem, gdy użytkownik kliknie element z promptem.
    • Polecenie: po kliknięciu uruchamia zarejestrowane polecenie po ukośniku lub szybkie polecenie. Działań związanych z wiadomościami nie można mapować na prompty rozpoczynające.
  5. Skonfiguruj prompta na podstawie wybranego typu:

    • Jeśli wybierzesz Prompt tekstowy:

      1. W polu Tytuł wpisz tytuł prompta wyświetlany w elemencie (maksymalnie 30 znaków). Tytuł nie może zawierać ukośników ani ukośników lewych.
      2. W polu Tekst prompta wpisz tekst, który ma się pojawiać na pasku tworzenia wiadomości (maksymalnie 60 znaków). Tekst prompta nie może zawierać ukośników ani ukośników lewych.
      3. Opcjonalnie: dodaj zlokalizowane tytuły i teksty dla użytkowników posługujących się innymi językami:
      4. W sekcji Zlokalizowane instrukcje kliknij Dodaj język.
      5. W sekcji Język wybierz obsługiwany język z menu.
      6. W polu Zlokalizowany tytuł wpisz zlokalizowany tytuł (maksymalnie 30 znaków).
      7. W polu Przetłumaczony tekst wpisz przetłumaczony tekst prośby (maksymalnie 60 znaków).
      8. W razie potrzeby powtórz te czynności, aby dodać więcej języków.
    • Jeśli wybierzesz Polecenie:

      1. W polu Identyfikator polecenia wybierz polecenie z menu.
  6. Kliknij Gotowe, a następnie u dołu strony kliknij Zapisz.

Obsługa ponownych prób wywołania HTTP do usługi

Jeśli żądanie HTTPS do Twojej usługi nie powiedzie się (np. z powodu przekroczenia limitu czasu, tymczasowej awarii sieci lub kodu stanu HTTPS innego niż 2xx), Google Chat może spróbować ponownie dostarczyć wiadomość kilka razy w ciągu kilku minut (ale nie jest to gwarantowane). W związku z tym w niektórych sytuacjach aplikacja do Google Chat może otrzymać to samo zdarzenie kilka razy. Jeśli żądanie zostanie zrealizowane, ale zwróci nieprawidłowy ładunek odpowiedzi, Google Chat nie ponowi żądania.

Obiekty zdarzeń

Aplikacje do Google Chat otrzymują obiekty zdarzeń, gdy uruchamiany jest aktywator Google Chat lub gdy użytkownicy Google Chat wchodzą w interakcję z interfejsem aplikacji do Google Chat (np. klikają przycisk lub przesyłają okno). Obiekt zdarzenia umożliwia używanie danych interakcji do reagowania lub aktualizowania interfejsu.

W 2025 r. aplikacje Google Chat zostały rozszerzone o obsługę zdarzeń dodatków, co jest domyślnym ustawieniem w przypadku nowych aplikacji Google Chat od lipca 2025 r. W dokumentacji Google Chat zdarzenia dodatków są standardowym typem zdarzeń wyświetlanym w przewodnikach i przykładowych kodach. Dokumentacja zdarzeń Google Chat (w przypadku aplikacji Google Chat, które nie są dodatkami do Google Workspace) jest podzielona na zwinięte sekcje (np. Aplikacje Google Chat, które nie są dodatkami: odbieranie zdarzeń interakcji i odpowiadanie na nie).

Określanie typów zdarzeń i odpowiedzi

Gdy aplikacja Google Chat otrzyma obiekt zdarzenia, struktura ładunku i sposób odpowiedzi zależą od tego, czy aplikacja Google Chat jest skonfigurowana jako dodatek do Google Workspace.

Aby sprawdzić, jakiego typu obiekty zdarzeń otrzymuje Twoja aplikacja i jak powinna na nie reagować, sprawdź konfigurację aplikacji, korzystając z tej tabeli:

Typ aplikacji Odbiera zdarzenia dodatków
(domyślne ustawienie dla nowych aplikacji utworzonych po lipcu 2025 r.)
Odbiera zdarzenia Google Chat
(poprzednie ustawienie domyślne, przed lipcem 2025 r.)
Aplikacje Apps Script
Sprawdź plik manifestu (appsscript.json).
Obiekt chat jest skonfigurowany w addOns:
{
  "addOns": {
    "chat": {}
  }
}
Obiekt chat jest skonfigurowany w głównym katalogu pliku manifestu:
{
  "chat": {}
}
Inne aplikacje
Sprawdź stronę Konfiguracja interfejsu Google Chat API
Pole wyboru „Utwórz tę aplikację do Google Chat jako dodatek do Google Workspace” jest zaznaczone. Pole wyboru „Utwórz tę aplikację do Google Chat jako dodatek do Google Workspace” nie jest zaznaczone.
Gdzie można znaleźć dokumentację W przewodnikach i przykładowych kodach

Dokumentacja referencyjna zdarzeń: obiekty zdarzeń dodatków
Zwijane sekcje (np. Aplikacje do Google Chat, które nie są dodatkami: odbieranie zdarzeń interakcji i odpowiadanie na nie)

Dokumentacja zdarzeń: Zdarzenia interakcji w interfejsie Chat API
Jak odpowiadać Zwróć działanie, np. DataActions lub RenderActions.
Zobacz, jak odpowiedzieć działaniem
Zwróć zasób Message.
Zobacz, jak odpowiedzieć wiadomością

Ładunki obiektów zdarzeń

Każdy obiekt zdarzenia dodatków zawiera obiekt commonEventObject ze szczegółowymi informacjami o hoście i platformie (hostApp: "CHAT", clientPlatform, userLocale, userTimezone, parameters i formInputs) oraz obiekt chat zawierający kontekst dotyczący Google Chat:

  • W przypadku aktywatora Strona główna aplikacji (gdy użytkownik otwiera kartę Strona główna w czacie indywidualnym w aplikacji Google Chat) obiekt chat zawiera pola chat.user i chat.eventTime bez pola unii payload. Gdy użytkownik kliknie przycisk na karcie strony głównej, obiekt zdarzenia zawiera chat.buttonClickedPayload oraz commonEventObject.parameters (i commonEventObject.formInputs, jeśli karta zawiera dane wejściowe formularza).
  • W przypadku interakcji w pokoju i wiadomości (Dodano do pokoju, Wiadomość, Usunięto z pokoju, Polecenie aplikacji lub interakcje z przyciskami i widżetami) obiekt chat zawiera chat.user, chat.space, chat.eventTime i odpowiednie dane interakcji:
    • messagePayload: zawiera space, message i configCompleteRedirectUri, gdy użytkownik wysyła wiadomość.
    • addedToSpacePayload: zawiera space, interactionAdd i configCompleteRedirectUri, gdy aplikacja Google Chat zostanie dodana do pokoju.
    • removedFromSpacePayload: zawiera space, gdy aplikacja Google Chat zostanie usunięta z pokoju.
    • buttonClickedPayload: zawiera space, message, isDialogEvent i dialogEventType, gdy użytkownik kliknie przycisk na karcie lub w oknie.
    • widgetUpdatedPayload: zawiera space, gdy użytkownik wchodzi w interakcję z widżetem, np. wpisuje tekst w menu wielokrotnego wyboru z zewnętrznym źródłem danych.
    • appCommandPayload: zawiera space, message, appCommandMetadata, isDialogEvent, dialogEventType i configCompleteRedirectUri, gdy użytkownik wywołuje polecenie aplikacji.

Gdy sesje rozmów są włączone w pokoju czatu indywidualnego z aplikacją Google Chat, obiekt space w ładunku interakcji (np. chat.messagePayload.space, chat.addedToSpacePayload.space, chat.buttonClickedPayload.space, chat.widgetUpdatedPayload.space lub chat.appCommandPayload.space) zawiera sessionState (ustawiony na THREAD) i sessionEnableTime, a obiekt thread (chat.messagePayload.message.thread, chat.buttonClickedPayload.message.thread, chat.appCommandPayload.message.thread lub chat.appCommandPayload.thread) identyfikuje wątek sesji (spaces/{space}/threads/{thread}).

Więcej informacji o obiektach zdarzeń dodatków w Google Chat i innych aplikacjach Google Workspace znajdziesz w artykule o obiektach zdarzeń.

Przekaż odpowiedź

W tej sekcji wyjaśniamy, jak aplikacje do Google Chat używają działań do synchronicznego reagowania na interakcje użytkowników.

Aby odpowiedzieć działaniem, aplikacja Google Chat musi odpowiedzieć w ciągu 30 sekund, a odpowiedź musi dotyczyć pokoju, w którym miała miejsce interakcja. Te odpowiedzi synchroniczne nie wymagają uwierzytelniania. Jeśli aplikacja do Google Chat potrzebuje więcej niż 30 sekund lub musi działać poza pokojem, skonfiguruj uwierzytelnianie i odpowiadaj asynchronicznie za pomocą interfejsu Google Chat API.

Aby synchronicznie odpowiadać na interakcje użytkowników, aplikacja Google Chat obsługuje przychodzący obiekt zdarzenia i zwraca jeden z tych obiektów JSON:

  • DataActions: tworzy lub aktualizuje wiadomości na czacie (CreateMessageAction, UpdateMessageAction) lub dołącza podglądy linków (UpdateInlinePreviewAction) za pomocą chatDataActionMarkup.
  • RenderActions: tworzy, aktualizuje lub zamyka stronę główną lub okno (pushCard, updateCard, endNavigation: "CLOSE_DIALOG") albo udostępnia dynamiczne sugestie dotyczące danych wejściowych w menu wielokrotnego wyboru (modifyCard).
  • AuthorizationError: wyświetla użytkownikom podstawową kartę autoryzacji (basic_authorization_prompt) umożliwiającą zalogowanie się lub uwierzytelnienie w usłudze zewnętrznej.

W tabeli poniżej pokazano, jak aplikacje do Google Chat mogą reagować za pomocą działań. Aplikacje do Google Chat mogą zwracać obiekty JSON bezpośrednio lub tworzyć odpowiedzi za pomocą AddOnResponseService i CardService w Apps Script.

Odpowiedź aplikacji do obsługi czatu Wymagane działanie do zwrócenia (JSON) Wymagane działanie, aby zwrócić (Apps Script)
wysłać wiadomość lub zaktualizować wiadomość; DataActions (createMessageAction lub updateMessageAction) DataActionsResponse
Wyświetlać podgląd linków w wiadomościach wysyłanych przez użytkowników Google Chat w pokoju. DataActions (updateInlinePreviewAction) DataActionsResponse
renderować lub aktualizować stronę główną na karcie Strona główna czatu, RenderActions (pushCard lub updateCard) ActionResponse
otwieranie, aktualizowanie i zamykanie okna; RenderActions (pushCard, updateCard lub endNavigation: "CLOSE_DIALOG") ActionResponse
Aby zbierać informacje z karty lub okna, zasugeruj elementy wyboru na podstawie tego, co użytkownicy wpisują w menu wielokrotnego wyboru. RenderActions (modifyCard) ActionResponse
Poproś o konfigurację lub autoryzację usługi zewnętrznej. AuthorizationError (basic_authorization_prompt) AuthorizationException

Odpowiedz za pomocą wiadomości

Aplikacje do Google Chat mogą odpowiadać wiadomością na dowolne z tych aktywatorów lub interakcji:

  • Wyzwalacze wiadomości, np. gdy użytkownicy @wspominają aplikację do Google Chat lub wysyłają do niej wiadomość na czacie.
  • Dodanie do pokoju, np. gdy użytkownicy instalują aplikację Google Chat z Google Workspace Marketplace lub dodają ją do pokoju.
  • Polecenie aplikacji, np. gdy użytkownicy wywołują polecenie po ukośniku lub szybkie polecenie.
  • kliknięcia przycisków na kartach w wiadomościach lub oknach; Na przykład gdy użytkownicy wpisują informacje i klikają przycisk przesyłania.

Aplikacje do Google Chat mogą zawierać w wiadomości dowolne z tych elementów:

  • Tekst zawierający hiperlinki, @wzmianki i emotikony. Zobacz Formatowanie wiadomości.
  • co najmniej 1 kartę, która może pojawić się w wiadomości lub otworzyć się w nowym oknie jako okno dialogowe; Więcej informacji znajdziesz w artykule Tworzenie kart dla aplikacji Google Chat.
  • co najmniej 1 widżet dodatkowy, czyli przycisk, który pojawia się po tekście lub kartach w wiadomości.

Aby odpowiedzieć wiadomością, zwróć DataActions z obiektem CreateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "createMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Zastąp MESSAGE zasobem Message z interfejsu Chat API.

W tym przykładzie aplikacja do Google Chat tworzy i wysyła wiadomość tekstową z wprowadzeniem, gdy zostanie dodana do pokoju, odpowiadając na aktywator Dodano do pokoju za pomocą DataActions:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The request object from Google Chat.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  const chatEvent = req.body.chat;
  // Send an onboarding message when added to a Chat space
  if (chatEvent.addedToSpacePayload) {
    res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
    }}}}});
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  chat_event = request.get_json()["chat"]
  if "addedToSpacePayload" in chat_event:
    return json.jsonify({ "hostAppDataAction": { "chatDataAction": {
      "createMessageAction": { "message": {
        "text": 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
        'To learn what else I can do, type `/help`.'
      }}
    }}})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    JsonNode chatEvent = event.at("/chat");
    if (!chatEvent.at("/addedToSpacePayload").isEmpty()) {
      return new GenericJson() { {
        put("hostAppDataAction", new GenericJson() { {
          put("chatDataAction", new GenericJson() { {
            put("createMessageAction", new GenericJson() { {
              put("message", new Message().setText(
                "Hi, Cymbal at your service. I help you manage your calendar " +
                "from Google Chat. Take a look at your schedule today by typing " +
                "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
                "To learn what else I can do, type `/help`."
              ));
            } });
          } });
        } });
      } };
    }
    return new GenericJson();
  }
}

Google Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {Object} Response from the Chat app.
 */
function onAddedToSpace(event) {
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: 'Hi, Cymbal at your service. I help you manage your calendar ' +
          'from Google Chat. Take a look at your schedule today by typing ' +
          '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. ' +
          'To learn what else I can do, type `/help`.'
  }}}}};
}

Przykładowy kod zwraca tę wiadomość tekstową:

Przykładowa wiadomość wprowadzająca.

Aktualizowanie wiadomości

Aplikacje do Google Chat mogą też aktualizować wysyłane przez siebie wiadomości. Na przykład aplikacja do Google Chat może zaktualizować wiadomość po przesłaniu przez użytkownika okna lub kliknięciu przycisku na karcie w wiadomości.

Aby zaktualizować wiadomość aplikacji do Google Chat w odpowiedzi na interakcję, zwróć DataActions z UpdateMessageAction:

{
  "hostAppDataAction": {
    "chatDataAction": {
      "updateMessageAction": {
        "message": <var>MESSAGE</var>
      }
    }
  }
}

Zastąp MESSAGE zasobem Message z interfejsu Chat API.

Aplikacje do Google Chat mogą też aktualizować wiadomości wysłane przez użytkownika, aby dołączyć kartę podglądu linku za pomocą updateInlinePreviewAction. Więcej informacji znajdziesz w artykule Wyświetlanie podglądu linków.

Odpowiadanie asynchroniczne za pomocą interfejsu Google Chat API

Zamiast zwracać działanie synchronicznie, aplikacje Google Chat mogą potrzebować wywołania interfejsu Google Chat API, aby odpowiedzieć na interakcję lub wysłać wiadomości proaktywne. Na przykład aplikacje do Google Chat muszą wywoływać interfejs Google Chat API, aby wykonywać te czynności:

  • odpowiada na interakcję po 30 sekundach (np. po zakończeniu długotrwałego zadania).
  • Wysyłaj wiadomości zgodnie z harmonogramem lub wysyłaj powiadomienia o zmianach w zasobach zewnętrznych.
  • wykonywać zadań poza pokojem, w którym doszło do interakcji;
  • wykonywać w Google Chat zadania, które nie są dostępne jako działania synchroniczne, takie jak wyświetlanie listy pokoi lub dodawanie osób do pokoju;
  • wykonywać zadania w imieniu użytkownika Google Chat (co wymaga uwierzytelnienia użytkownika);

Aby uniknąć wyświetlania użytkownikowi komunikatu o błędzie informującego, że aplikacja Google Chat nie odpowiada, gdy odpowiadasz na interakcję po 30 sekundach, musisz potwierdzić otrzymanie obiektu zdarzenia w ciągu 30 sekund, zwracając pustą odpowiedź:

Node.js

async function onEvent(req, res) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return res.send({});
};

Python

def on_event(event) -> dict:
  # Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return {}

Java

public String onEvent(JsonNode event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return "{}";
}

Google Apps Script

function onEvent(event) {
  // Trigger asynchronous job that will respond using the Google Chat API.
  ...

  // Respond with an empty response to the Google Chat platform.
  return null;
}

Aby wysłać wiadomość za pomocą interfejsu Chat API, skonfiguruj uwierzytelnianie i wywołaj metodę spaces.messages.create. Instrukcje znajdziesz w artykule Wysyłanie wiadomości. Przewodniki dotyczące korzystania z dodatkowych metod interfejsu Chat API znajdziesz w omówieniu interfejsu Chat API.

Aplikacje do Google Chat, które nie są dodatkami: odbieranie interakcji użytkowników i odpowiadanie na nie.

Aplikacje do Google Chat, które nie są dodatkami do Google Workspace, otrzymują zdarzenia interakcji z interfejsem Chat API (Event) zamiast obiektów zdarzeń dodatków do Google Workspace (EventObject) i odpowiadają, zwracając zasób Message zamiast działania.

Aby przekształcić aplikację Google Chat, która nie jest dodatkiem, na platformę dodatków do Google Workspace, zapoznaj się z artykułem Przekształcanie aplikacji Google Chat w dodatek do Google Workspace.

Typy zdarzeń interakcji

W przypadku każdego typu interakcji użytkownika Google Chat wysyła do aplikacji Google Chat, która nie jest dodatkiem, obiekt Event, którego typ jest reprezentowany przez pole eventType:

Interakcja użytkownika eventType Typowa odpowiedź z aplikacji do Google Chat, która nie jest dodatkiem
Użytkownik wysyła wiadomość do aplikacji do Google Chat. Na przykład @wzmiankuje aplikację do Google Chat lub używa polecenia po ukośniku. MESSAGE Aplikacja do Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja do Google Chat odpowiada na polecenie po ukośniku /about wiadomością, która wyjaśnia, jakie zadania może wykonać.
Użytkownik dodaje aplikację do Google Chat do pokoju. ADDED_TO_SPACE Aplikacja do Google Chat wysyła wiadomość powitalną, która wyjaśnia, do czego służy aplikacja i jak użytkownicy w pokoju mogą z niej korzystać.
Użytkownik usuwa aplikację do Google Chat z pokoju. REMOVED_FROM_SPACE Aplikacja Google Chat usuwa wszystkie powiadomienia przychodzące skonfigurowane dla pokoju (np. usuwa webhook) i czyści pamięć wewnętrzną.
Użytkownik klika przycisk na karcie w wiadomości, oknie lub na stronie głównej aplikacji Google Chat. CARD_CLICKED Aplikacja do Google Chat przetwarza i przechowuje dane przesłane przez użytkownika lub zwraca inną kartę.
Użytkownik otwiera stronę główną aplikacji Google Chat, klikając kartę Strona główna w wiadomości 1:1. APP_HOME Aplikacja do Google Chat zwraca statyczną lub interaktywną kartę ze strony głównej.
Użytkownik przesyła formularz ze strony głównej aplikacji do Google Chat. SUBMIT_FORM Aplikacja do Google Chat przetwarza i przechowuje dane przesłane przez użytkownika lub zwraca inną kartę.
Użytkownik wywołuje polecenie za pomocą szybkiego polecenia. APP_COMMAND Aplikacja do Google Chat odpowiada na podstawie wywołanego polecenia. Na przykład aplikacja do Google Chat odpowiada na polecenie Informacje wiadomością, która wyjaśnia, jakie zadania może wykonywać.

Aby zobaczyć wszystkie obsługiwane zdarzenia interakcji i przykładowe ładunki JSON, zapoznaj się z artykułem Typy zdarzeń interakcji z aplikacją Google Chat i dokumentacją referencyjną EventType.

Zdarzenia interakcji z okien dialogowych

Jeśli aplikacja do Google Chat, która nie jest dodatkiem, otwiera okna, zdarzenie interakcji zawiera te dodatkowe informacje, których możesz użyć do przetworzenia odpowiedzi:

  • Pole isDialogEvent ma wartość true.
  • Atrybut DialogEventType (REQUEST_DIALOG, SUBMIT_DIALOG lub CANCEL_DIALOG) określa, czy interakcja powoduje otwarcie okna, przesłanie informacji z okna czy zamknięcie okna.

Zdarzenia interakcji w pokojach z sesjami

Gdy sesje rozmowy są włączone w przestrzeni wiadomości prywatnych 1:1 z aplikacją Google Chat, która nie jest dodatkiem, pole najwyższego poziomu space zdarzenia interakcji zawiera space.sessionState (ustawione na THREAD) i space.sessionEnableTime, a message.thread lub thread identyfikuje wątek sesji.

Konfigurowanie aplikacji do Google Chat, która nie jest dodatkiem, do odbierania zdarzeń interakcji

  1. W konsoli Google Cloud otwórz stronę Konfiguracja interfejsu Chat API:

    Otwórz stronę konfiguracji interfejsu Chat API

  2. W sekcji Funkcje interaktywne odznacz Utwórz tę aplikację Google Chat jako dodatek do Google Workspace i skonfiguruj Funkcje, pojedynczy punkt końcowy Ustawienia połączenia (adres URL punktu końcowego HTTP, Apps Script, nazwa tematu Cloud Pub/Sub lub Dialogflow), Polecenia, Prompty początkowe, Podglądy linków i Widoczność.

  3. Kliknij Zapisz.

Odpowiadanie za pomocą wiadomości w aplikacji do Google Chat, która nie jest dodatkiem

Aby odpowiedzieć synchronicznie w aplikacji Google Chat, która nie jest dodatkiem, zwróć bezpośrednio obiekt Message. Poniższy przykład odpowiada na zdarzenie interakcji ADDED_TO_SPACE wiadomością tekstową:

Node.js

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} req The event object from Chat API.
 * @param {Object} res The response object from the Chat app.
 */
exports.cymbalApp = function cymbalApp(req, res) {
  // Send an onboarding message when added to a Chat space
  if (req.body.type === 'ADDED_TO_SPACE') {
    res.json({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
        'from Google Chat. Take a look at your schedule today by typing ' +
        '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
        'learn what else I can do, type `/help`.'
    });
  }
};

Python

from flask import Flask, request, json
app = Flask(__name__)

@app.route('/', methods=['POST'])
def cymbal_app():
  """Sends an onboarding message when the Chat app is added to a space.

  Returns:
    Mapping[str, Any]: The response object from the Chat app.
  """
  event = request.get_json()
  if event['type'] == 'ADDED_TO_SPACE':
    return json.jsonify({
      'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To ' +
      'learn what else I can do, type `/help`.'
    })
  return json.jsonify({})

Java

@SpringBootApplication
@RestController
public class App {
  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /*
   * Sends an onboarding message when the Chat app is added to a space.
   *
   * @return The response object from the Chat app.
   */
  @PostMapping("/")
  @ResponseBody
  public Message onEvent(@RequestBody JsonNode event) {
    switch (event.get("type").asText()) {
      case "ADDED_TO_SPACE":
        return new Message().setText(
          "Hi, Cymbal at your service. I help you manage your calendar " +
          "from Google Chat. Take a look at your schedule today by typing " +
          "`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. " +
          "To learn what else I can do, type `/help`.");
      default:
        return new Message();
    }
  }
}

Google Apps Script

/**
 * Sends an onboarding message when the Chat app is added to a space.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onAddToSpace(event) {
  return {
    'text': 'Hi, Cymbal at your service. I help you manage your calendar ' +
      'from Google Chat. Take a look at your schedule today by typing ' +
      '`/checkCalendar`, or schedule a meeting with `/scheduleMeeting`. To learn ' +
      'what else I can do, type `/help`.'
  };
}