Otrzymuj interakcje użytkowników i reaguj na nie

Na tej stronie opisaliśmy, jak aplikacja Google Chat może odbierać interakcje z użytkownikami i na nie reagować. Nazywamy je też zdarzeniami interakcji z aplikacją Google Chat.

Na tej stronie dowiesz się, jak:

• Skonfiguruj aplikację Google Chat tak, aby odbierała zdarzenia interakcji.
• przetwarzać zdarzenie interakcji w swojej infrastrukturze;
• W razie potrzeby reaguj na zdarzenia interakcji.

Wymagania wstępne

Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywną aplikację do obsługi czatu, wykonaj jedno z tych krótkich wprowadzeń opartych na architekturze aplikacji, której chcesz używać:

• Usługa HTTP w Google Cloud Functions
• Skrypt Google Apps Script
• Google Cloud Dialogflow CX,
• Google Cloud Pub/Sub

Typy zdarzeń interakcji

Zdarzenie interakcji z aplikacją Google Chat reprezentuje dowolne działanie wykonywane przez użytkownika w celu wywołania aplikacji do obsługi czatu lub interakcji z nią, np. @wzmianki o aplikacji Google Chat 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, reprezentowane w interfejsie Chat API jako typ Event. Aplikacja Google Chat może użyć tego zdarzenia do przetworzenia interakcji i opcjonalnie do odpowiedzi wiadomością.

W przypadku każdego typu interakcji Google Chat wysyła inny typ zdarzenia tej interakcji, dzięki czemu aplikacja Google Chat odpowiednio obsługuje poszczególne typy zdarzeń. Typ zdarzenia interakcji jest reprezentowany za pomocą obiektu eventType.

Na przykład Google Chat używa zdarzenia typu ADDED_TO_SPACE w przypadku każdej interakcji, w ramach której użytkownik dodaje aplikację Google Chat do pokoju. Dzięki temu aplikacja ta może natychmiast wysłać wiadomość powitalną w pokoju.

Rysunek 1. Gdy użytkownik dodaje aplikację Google Chat do pokoju, otrzymuje ona zdarzenie interakcji ADDED_TO_SPACE, które obsługuje, aby wysłać wiadomość powitalną w pokoju.

Poniższa tabela zawiera informacje o popularnych interakcjach użytkowników, typie zdarzenia interakcji, które otrzymują aplikacje do obsługi czatu, oraz o tym, jak te aplikacje zwykle na nie reagują:

Interakcja użytkownika	eventType	Typowa odpowiedź z aplikacji Google Chat
Użytkownik wywołuje aplikację do obsługi czatu, używając @wzmianki lub polecenia po ukośniku.	MESSAGE	Aplikacja Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja Google Chat odpowiada na polecenie /about wiadomością z wyjaśnieniem zadań, które może wykonać.
Użytkownik dodaje aplikację Google Chat do pokoju.	ADDED_TO_SPACE	Aplikacja Google Chat wysyła wiadomość powitalną, która wyjaśnia, do czego służy i jak użytkownicy w pokoju mogą z niej korzystać.
Użytkownik usuwa aplikację Google Chat z pokoju.	REMOVED_FROM_SPACE	Aplikacja Google Chat usunie wszystkie przychodzące powiadomienia skonfigurowane dla pokoju (takie jak usunięcie webhooka) i zwolni pamięć wewnętrzną.
Użytkownik klika przycisk na karcie z poziomu wiadomości, okna lub strony głównej aplikacji Google Chat.	CARD_CLICKED	Aplikacja Google Chat przetwarza i przechowuje przesłane przez użytkownika dane lub zwraca inną kartę.
Użytkownik otwiera stronę główną aplikacji Czat, klikając kartę Strona główna w wiadomości 1:1.	APP_HOME	Aplikacja Google Chat zwraca stałą lub interaktywną kartę ze strony głównej.
Użytkownik przesyła formularz ze strony głównej aplikacji Google Chat.	SUBMIT_FORM	Aplikacja Google Chat przetwarza i przechowuje przesłane przez użytkownika dane lub zwraca inną kartę.

Wszystkie obsługiwane zdarzenia interakcji znajdziesz w dokumentacji referencyjnej EventType.

Zdarzenia interakcji z okien

Jeśli w Twojej aplikacji Google Chat zostaną otwarte okna, zdarzenie interakcji zawiera te dodatkowe informacje, których możesz użyć do przetworzenia odpowiedzi:

• isDialogEvent ma wartość true.
• DialogEventTypeokreśla, czy interakcja powoduje otwarcie okna dialogowego, przesyła informacje z okna dialogowego czy zamyka okno dialogowe.

W tabeli poniżej znajdziesz typowe interakcje z oknami, odpowiadające im typy zdarzeń w oknach oraz opis typowych odpowiedzi aplikacji do obsługi czatu:

Interakcja użytkownika z oknem	Typ zdarzenia dialogowego	Typowa odpowiedź
Użytkownik uruchamia prośbę o wyświetlenie okna. Na przykład używają polecenia po ukośniku lub klikają przycisk w wiadomości.	REQUEST_DIALOG	Okno otworzy się aplikacja Google Chat.
Użytkownik przesyła informacje w oknie, klikając przycisk.	SUBMIT_DIALOG	Aplikacja Google Chat przejdzie do innego okna lub je zamknie, aby dokończyć interakcję.
Użytkownik zamyka okno przed przesłaniem informacji.	CANCEL_DIALOG	Opcjonalnie aplikacja Google Chat może odpowiedzieć nową wiadomością albo zaktualizować wiadomość lub kartę, z której użytkownik otworzył okno.

Więcej informacji znajdziesz w artykule Otwieranie dialogów interaktywnych.

Odbieranie zdarzeń interakcji z aplikacją Google Chat

Z tej sekcji dowiesz się, jak odbierać i przetwarzać zdarzenia interakcji w aplikacji Google Chat.

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

Nie wszystkie aplikacje do obsługi czatu 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żliwia jej odbieranie, przetwarzanie i odpowiadanie na zdarzenia interakcji. Więcej informacji o projektowaniu aplikacji Google Chat znajdziesz w artykule na temat architektur implementacji aplikacji do obsługi czatu.

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 Chat API

2. W sekcji Funkcje interaktywne przejrzyj ustawienia i zaktualizuj je w zależności od funkcji, które chcesz tworzyć:

   Pole	Opis
   Funkcjonalność	Wymagane. Zbiór pól, które określają, w jaki sposób aplikacja do obsługi czatu może wchodzić w interakcje z użytkownikami: Odbieranie wiadomości 1:1: 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 elementów: URL punktu końcowego HTTP: punkt końcowy HTTPS, który hostuje implementację aplikacji Chat. Apps Script: identyfikator wdrożenia projektu Apps Script, w którym zaimplementowano aplikację Google Chat. Nazwa tematu Cloud Pub/Sub: temat Pub/Sub subskrybowany przez aplikację Google Chat jako punkt końcowy. Dialogflow: rejestruje aplikację Google Chat z integracją Dialogflow. Więcej informacji znajdziesz w artykule Tworzenie aplikacji Google Chat Dialogflow, która rozumie język naturalny.
   Polecenia rozpoczynające się ukośnikiem	Opcjonalnie: Polecenia, które mogą wyświetlać się użytkownikom w Google Chat. Umożliwia użytkownikom wyświetlanie głównych działań w aplikacji Google Chat w Google Chat i wybieranie określonych działań. Więcej informacji znajdziesz w artykule Odpowiedzi na znaki ukośnika w 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 sekcji Podgląd linków.
   Widoczność	Opcjonalnie: Do pięciu osób lub co najmniej jedna grupa Google, które mogą wyświetlać i instalować Twoją aplikację Google Chat. Użyj tego pola, aby przetestować aplikację Google Chat lub udostępnić ją swojemu zespołowi. Więcej informacji znajdziesz w artykule Testowanie funkcji interaktywnych.

3. Kliknij Zapisz. Po zapisaniu konfiguracji aplikacji Google Chat jest ona dostępna dla określonych użytkowników w organizacji Google Workspace.

Aplikacja Google Chat jest teraz skonfigurowana tak, aby odbierać zdarzenia interakcji z Google Chat.

Obsługa powtórzeń wywołań HTTP do usługi

Jeśli nie uda się wysłać żądania HTTPS do usługi (np. przekroczą limit czasu, tymczasowa awaria sieci lub kod stanu HTTPS inny niż 2xx), Google Chat może ponowić próbę dostarczenia wiadomości w ciągu kilku minut (nie jest to gwarantowane). W związku z tym w pewnych sytuacjach aplikacja do obsługi czatu może kilka razy otrzymać tę samą wiadomość. Jeśli żądanie zostanie zrealizowane, ale zwróci nieprawidłowy ładunek wiadomości, Google Chat nie spróbuje ponownie wykonać żądania.

Przetwarzanie zdarzeń interakcji i reagowanie na nie

Ta sekcja wyjaśnia, jak aplikacje Google Chat mogą przetwarzać zdarzenia interakcji i odpowiadać na nie.

Gdy aplikacja do obsługi czatu otrzyma zdarzenie interakcji z Google Chat, może ona odpowiadać na wiele sposobów. W wielu przypadkach interaktywne aplikacje do obsługi czatu odpowiadają użytkownikowi, wysyłając wiadomość. Aplikacja Google Chat może też wyszukiwać niektóre informacje ze źródła danych, zapisywać informacje o zdarzeniach interakcji i cokolwiek innego. To zachowanie definiuje aplikację Google Chat.

Aby odpowiedzieć synchronicznie, aplikacja Google Chat musi odpowiedzieć w ciągu 30 sekund, a jej odpowiedź musi zostać opublikowana w pokoju, w którym miała miejsce 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, aby przetworzyć odpowiedź. Przykłady ładunków zdarzeń znajdziesz w artykule Typy zdarzeń interakcji z aplikacją do Google Chat.

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

Wyświetlaj odpowiedź w trakcie jej generowania

Zdarzenia interakcji umożliwiają aplikacjom czatu reagowanie w czasie rzeczywistym lub synchronicznie. Synchroniczne odpowiedzi nie wymagają uwierzytelniania.

Aby odpowiedzieć w czasie rzeczywistym, aplikacja Google Chat musi zwrócić obiekt Message. Aby odpowiedzieć przy użyciu wiadomości w pokoju, obiekt Message może zawierać obiekty text, cardsV2 i accessoryWidgets. Aby używać go w przypadku innych typów odpowiedzi, zapoznaj się z tymi przewodnikami:

• Otwieranie interaktywnych okien dialogowych
• Linki do podglądu
• Przetwarzanie informacji przesłanych przez użytkowników

Uwaga: w przypadku zdarzeń interakcji REMOVED_FROM_SPACE aplikacje do czatu nie mogą odpowiadać obiektem Message, ponieważ nie są już w pokoju.

Odpowiedz za pomocą wiadomości

W tym przykładzie aplikacja Google Chat tworzy i wysyła SMS-a za każdym razem, gdy zostaje on dodany do pokoju. Aby dowiedzieć się więcej o sprawdzonych metodach wprowadzania użytkowników, przeczytaj artykuł Wprowadzanie użytkowników w aplikację Google Chat.

Aby wysłać SMS-a, gdy użytkownik doda Twoją aplikację Google Chat do pokoju, ta aplikacja zareaguje na zdarzenie interakcji ADDED_TO_SPACE. Aby odpowiedzieć na zdarzenia interakcji ADDED_TO_SPACE 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 taki komunikat tekstowy:

Odpowiadaj asynchronicznie

Czasami aplikacje do obsługi czatu muszą zareagować na zdarzenie interakcji po 30 sekundach lub wykonać zadanie poza pokojem, w którym to zdarzenie zostało wygenerowane. Aplikacja do obsługi czatu może na przykład odpowiadać użytkownikowi 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, zapoznaj się z sekcją Tworzenie wiadomości. Wskazówki dotyczące korzystania z dodatkowych metod interfejsu Chat API znajdziesz w artykule Omówienie interfejsu Chat API.

Powiązane artykuły

• Wyślij wiadomość
• Otwieranie interaktywnych okien dialogowych
• Linki do podglądu
• Czytanie danych z formularzy wprowadzonych przez użytkowników na kartach
• Reagowanie na polecenia po ukośniku
• Tworzenie strony głównej aplikacji Google Chat
• Weryfikowanie próśb z Google Chat
• Testowanie funkcji interaktywnych w aplikacjach Google Chat