Otrzymywanie zdarzeń interakcji i odpowiadanie na nie

Z tego artykułu dowiesz się, jak aplikacja Google Chat może otrzymywać interakcje użytkowników i na nie odpowiadać. Są one też nazywane zdarzeniami interakcji aplikacji Google Chat.

Na tej stronie dowiesz się, jak:

  • Skonfiguruj aplikację Google Chat tak, aby otrzymywała zdarzenia interakcji.
  • Przetwarzaj zdarzenie interakcji w swojej infrastrukturze.
  • W razie potrzeby odpowiadaj na zdarzenia interakcji.

Wymagania wstępne

Typy zdarzeń interakcji

Zdarzenie interakcji z aplikacją Google Chat reprezentuje każde działanie, które użytkownik wykonuje, aby wywołać aplikację do obsługi czatu lub wejść z nią w interakcję, np. @wzmianka o aplikacji do obsługi czatu lub dodanie jej do pokoju.

Gdy użytkownicy wchodzą w interakcję z aplikacją do obsługi czatu, Google Chat wysyła do niej zdarzenie interakcji, które jest reprezentowane jako typ Event w interfejsie Chat API. Aplikacja Chat może użyć tego zdarzenia do przetworzenia interakcji i opcjonalnie odpowiedzieć wiadomością.

W przypadku każdego typu interakcji użytkownika Google Chat wysyła inny typ zdarzenia interakcji, co pomaga aplikacji Google Chat odpowiednio obsługiwać każdy typ zdarzenia. Typ zdarzenia interakcji jest reprezentowany przez obiekt eventType.

Na przykład Google Chat używa typu zdarzeniaADDED_TO_SPACE w przypadku każdej interakcji, w której użytkownik dodaje aplikację do obsługi czatu do pokoju, aby aplikacja do obsługi czatu mogła natychmiast odpowiedzieć w pokoju wiadomością powitalną.

Aplikacja do obsługi czatu publikuje wiadomość powitalną.
Ilustracja 1. Gdy użytkownik doda aplikację Google Chat do pokoju, otrzyma ona zdarzenie interakcji ADDED_TO_SPACE, które obsłuży, aby wysłać w pokoju wiadomość powitalną.

W tabeli poniżej znajdziesz typowe interakcje użytkowników, typ zdarzenia interakcji, które otrzymują aplikacje do obsługi czatu, oraz sposób, w jaki aplikacje do obsługi czatu zwykle reagują:

Interakcja użytkownika eventType Typowa odpowiedź z aplikacji do obsługi czatu
Użytkownik wysyła wiadomość do aplikacji Google Chat. Na przykład @wspomina aplikację Google Chat lub używa polecenia po ukośniku. MESSAGE Aplikacja do czatu odpowiada na podstawie treści wiadomości. Na przykład aplikacja do obsługi czatu odpowiada na polecenie po ukośniku /about wiadomością, która wyjaśnia zadania, jakie może wykonać.
Użytkownik dodaje aplikację Google Chat do pokoju. ADDED_TO_SPACE Aplikacja Chat wysyła wiadomość wprowadzającą, która wyjaśnia, do czego służy i jak użytkownicy w pokoju mogą z nią wchodzić w interakcję.
Użytkownik usuwa aplikację Google Chat z pokoju. REMOVED_FROM_SPACE Aplikacja Chat usuwa wszystkie przychodzące powiadomienia 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 Chat przetwarza i przechowuje wszystkie dane przesłane przez użytkownika lub zwraca inną kartę.
Użytkownik otwiera stronę główną aplikacji do czatowania, klikając kartę Strona główna w wiadomości 1:1. APP_HOME Aplikacja Google Chat zwraca statyczną lub interaktywną kartę ze strony głównej.
Użytkownik przesyła formularz ze strony głównej aplikacji Chat. SUBMIT_FORM Aplikacja Chat przetwarza i przechowuje wszystkie dane przesłane przez użytkownika lub zwraca inną kartę.
Użytkownik wywołuje polecenie za pomocą szybkiego polecenia. APP_COMMAND Aplikacja Chat odpowiada na podstawie wywołanego polecenia. Na przykład aplikacja do obsługi czatu odpowiada na polecenie About wiadomością, która wyjaśnia, jakie zadania może wykonywać ta aplikacja.

Wszystkie obsługiwane zdarzenia interakcji znajdziesz w EventTypedokumentacji referencyjnej.

Zdarzenia interakcji z oknami

Jeśli aplikacja do obsługi czatu otwiera okna, zdarzenie interakcji zawiera te dodatkowe informacje, które możesz wykorzystać do przetworzenia odpowiedzi:

  • Wartość isDialogEvent to true.
  • Element DialogEventType określa, czy interakcja powoduje otwarcie okna, przesłanie informacji z okna czy zamknięcie okna.

W tabeli poniżej znajdziesz typowe interakcje z oknami, odpowiadające im typy zdarzeń okna i opis tego, jak aplikacje do obsługi czatu zwykle reagują:

Interakcja użytkownika z oknem Typ zdarzenia okna Typowa odpowiedź
Użytkownik wywołuje żądanie okna. Na przykład używają polecenia ze znakiem ukośnika lub klikają przycisk w wiadomości. REQUEST_DIALOG Aplikacja Chat otworzy okno.
Użytkownik przesyła informacje w oknie, klikając przycisk. SUBMIT_DIALOG Aplikacja Chat przechodzi do innego okna dialogowego lub zamyka okno dialogowe, aby zakończyć interakcję.
Użytkownik zamyka okno dialogowe przed przesłaniem informacji. CANCEL_DIALOG Opcjonalnie aplikacja Google Chat może odpowiedzieć nową wiadomością lub zaktualizować wiadomość lub kartę, z której użytkownik otworzył okno.

Więcej informacji znajdziesz w artykule Otwieranie interaktywnych okien dialogowych.

Odbieranie zdarzeń interakcji z aplikacją Google Chat

W tej sekcji opisano, jak odbierać i przetwarzać zdarzenia interakcji w aplikacji do czatu.

Konfigurowanie aplikacji Google Chat pod kątem otrzymywania zdarzeń interakcji

Nie wszystkie aplikacje Google Chat są interaktywne. Na przykład przychodzące webhooki mogą tylko wysyłać wiadomości wychodzące i nie mogą odpowiadać użytkownikom. Jeśli tworzysz interaktywną aplikację do czatu, musisz wybrać punkt końcowy, który umożliwi jej odbieranie, przetwarzanie i odpowiadanie na zdarzenia interakcji. Więcej informacji o projektowaniu aplikacji Google Chat znajdziesz w artykule Architektury implementacji aplikacji Google Chat.

W przypadku każdej funkcji interaktywnej, którą chcesz utworzyć, musisz zaktualizować konfigurację w interfejsie Chat API, aby Google Chat mógł wysyłać do Twojej aplikacji Google Chat powiązane zdarzenia interakcji:

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

    Otwórz stronę konfiguracji interfejsu Chat API

  2. W sekcji Funkcje interaktywne przejrzyj ustawienia i zaktualizuj je na podstawie funkcji, które chcesz utworzyć:

    Pole Opis
    Funkcje Wymagane. Zestaw pól, które określają, w jaki sposób aplikacja Google Chat może wchodzić w interakcje z użytkownikami. Domyślnie użytkownicy mogą znaleźć aplikację Google Chat i wysłać do niej wiadomość bezpośrednio w Google Chat.
    • Dołączanie do pokoi i rozmów grupowych: użytkownicy mogą dodawać aplikację Google Chat do pokoi i rozmów grupowych.
    Ustawienia połączenia Wymagane. Punkt końcowy aplikacji Google Chat, który jest jednym z tych adresów:
    • Adres URL punktu końcowego HTTP: punkt końcowy HTTPS, który hostuje implementację aplikacji Google Chat.
    • Apps Script: identyfikator wdrożenia projektu Apps Script, który implementuje aplikację Google Chat.
    • Nazwa tematu Cloud Pub/Sub: temat Pub/Sub, który aplikacja Google Chat subskrybuje jako punkt końcowy.
    • Dialogflow: rejestruje aplikację do obsługi czatu w integracji z Dialogflow. Więcej informacji znajdziesz w artykule Tworzenie aplikacji Dialogflow w Google Chat, która rozumie język naturalny.
    Polecenia Opcjonalnie. Polecenia po ukośniku i szybkie polecenia w aplikacji Google Chat. Polecenia umożliwiają użytkownikom żądanie działania lub korzystanie z określonej funkcji aplikacji Google Chat. Więcej informacji znajdziesz w artykule Odpowiadanie na polecenia aplikacji Google Chat.
    Podgląd linków Opcjonalnie. Wzorce adresów URL rozpoznawane przez aplikację do obsługi czatu, dla których może ona dostarczać dodatkowe treści, gdy użytkownicy wyślą linki. Więcej informacji znajdziesz w artykule Podgląd linków.
    Widoczność Opcjonalnie. Maksymalnie 5 osób lub co najmniej 1 grupa Google, która może wyświetlać i instalować aplikację do Google Chat. Użyj tego pola, aby przetestować aplikację do Google Chat lub udostępnić ją zespołowi. Więcej informacji znajdziesz w artykule Testowanie funkcji interaktywnych.

  3. Kliknij Zapisz. Gdy zapiszesz konfigurację aplikacji do obsługi czatu, będzie ona dostępna dla określonych użytkowników w organizacji Google Workspace.

Aplikacja Chat jest teraz skonfigurowana do odbierania zdarzeń interakcji z Google Chat.

Obsługa ponownych prób wywołań 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 ponowić próbę dostarczenia kilka razy w ciągu kilku minut (ale nie jest to gwarantowane). W niektórych sytuacjach aplikacja do obsługi czatu może otrzymać tę samą wiadomość kilka razy. Jeśli żądanie zostanie zrealizowane, ale zwróci nieprawidłowy ładunek wiadomości, Google Chat nie ponowi żądania.

przetwarzanie zdarzeń interakcji lub odpowiadanie na nie,

W tej sekcji wyjaśniamy, jak aplikacje Google Chat mogą przetwarzać zdarzenia interakcji i na nie odpowiadać.

Gdy aplikacja do obsługi czatu otrzyma zdarzenie interakcji z Google Chat, może odpowiedzieć na wiele sposobów. W wielu przypadkach interaktywne aplikacje do czatowania odpowiadają użytkownikowi wiadomością. Aplikacja Google Chat może też wyszukiwać informacje w źródle danych, rejestrować informacje o zdarzeniu interakcji lub wykonywać inne czynności. Ten sposób przetwarzania danych jest podstawą działania aplikacji Google Chat.

Aby odpowiedzieć synchronicznie, aplikacja do obsługi czatu musi odpowiedzieć w ciągu 30 sekund, a odpowiedź musi zostać opublikowana w pokoju, w którym nastąpiła interakcja. W przeciwnym razie aplikacja Google Chat może odpowiadać asynchronicznie.

W przypadku każdego zdarzenia interakcji aplikacje Google Chat otrzymują treść żądania, czyli ładunek JSON reprezentujący zdarzenie. Możesz użyć tych informacji do przetworzenia odpowiedzi. Przykłady ładunków zdarzeń znajdziesz w artykule Typy zdarzeń interakcji aplikacji Google Chat.

Ten diagram pokazuje, jak aplikacja Google Chat zwykle przetwarza różne typy zdarzeń interakcji lub na nie odpowiada:

Architektura przetwarzania zdarzeń interakcji przez aplikacje Google Chat.

Wyświetlaj odpowiedź w trakcie jej generowania

Zdarzenia interakcji umożliwiają aplikacjom do obsługi czatu odpowiadanie w czasie rzeczywistym lub synchronicznie. Odpowiedzi synchroniczne nie wymagają uwierzytelniania.

Aby odpowiedzieć w czasie rzeczywistym, aplikacja Chat musi zwrócić obiekt Message. Aby odpowiedzieć na wiadomość w pokoju, obiekt Message może zawierać obiekty text, cardsV2 i accessoryWidgets. Aby dowiedzieć się, jak korzystać z innych rodzajów odpowiedzi, zapoznaj się z tymi przewodnikami:

Odpowiedz za pomocą wiadomości

W tym przykładzie aplikacja Google Chat tworzy i wysyła wiadomość tekstową za każdym razem, gdy zostanie dodana do pokoju. Sprawdzone metody wprowadzania użytkowników do aplikacji znajdziesz w artykule Przedstawianie użytkownikom aplikacji na czacie.

Aby wysłać wiadomość tekstową, gdy użytkownik doda aplikację Google Chat do pokoju, aplikacja Google Chat odpowiada na ADDED_TO_SPACE zdarzenie interakcji. Aby odpowiadać na ADDED_TO_SPACEzdarzenia interakcji za pomocą wiadomości tekstowej, użyj tego kodu:

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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat space.');
  }

  // 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`.'
    });
  }
};

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. An onboarding message that
 * introduces the app and helps people get started with it.
 */
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`.'
  }
}

Przykładowy kod zwraca ten SMS:

Przykładowa wiadomość wprowadzająca

Odpowiadanie asynchroniczne

Czasami aplikacje w Google Chat muszą odpowiedzieć na zdarzenie interakcji po 30 sekundach lub wykonać zadania poza pokojem, w którym wygenerowano zdarzenie interakcji. Na przykład aplikacja do obsługi czatu może potrzebować odpowiedzi dla użytkownika po zakończeniu długotrwałego zadania. W takim przypadku aplikacje Google Chat mogą odpowiadać asynchronicznie, wywołując interfejs Google Chat API.

Aby utworzyć wiadomość za pomocą interfejsu Chat API, zobacz Tworzenie wiadomości. Więcej informacji o korzystaniu z dodatkowych metod interfejsu Chat API znajdziesz w omówieniu interfejsu Chat API.