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 włączono funkcje interaktywne. Aby utworzyć interaktywną aplikację czatu, wykonaj jeden z tych samouczków w zależności od architektury aplikacji, której chcesz użyć:

• Usługa HTTP z Google Cloud Functions.
• 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 z użytkownikiem Google Chat wysyła inny typ zdarzenia interakcji, co pomaga aplikacji Google Chat odpowiednio obsługiwać 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 doda aplikację Google Chat do pokoju, ta otrzyma zdarzenie interakcji ADDED_TO_SPACE, które przetworzy na 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 komunikat wprowadzający, który wyjaśnia, do czego służy i jak użytkownicy w pokoju mogą wchodzić z nim w interakcję.
Użytkownik usuwa aplikację Google Chat z pokoju.	REMOVED_FROM_SPACE	Aplikacja Google Chat usuwa wszystkie przychodzące powiadomienia skonfigurowane dla pokoju (np. usuwanie webhooka) i czyści pamięć wewnętrzną.
Użytkownik klika przycisk na karcie w wiadomości, oknie lub na stronie głównej w aplikacji Google Chat.	CARD_CLICKED	Aplikacja Google Chat przetwarza i przechowuje wszystkie dane przesłane przez użytkownika 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 wszystkie dane przesłane przez użytkownika lub zwraca inną kartę.

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

Zdarzenia interakcji z dialogów

Jeśli aplikacja Google Chat otwiera dialogi, zdarzenie interakcji zawiera te dodatkowe informacje, które możesz wykorzystać 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 informacje o typowych interakcjach z dialogami, odpowiadających im typach zdarzeń dialogu oraz o tym, jak aplikacje do czatu zwykle reagują:

Interakcja użytkownika z dialogiem	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	Aplikacja Google Chat otworzy okno.
Użytkownik przesyła informacje w oknie, klikając przycisk.	SUBMIT_DIALOG	Aplikacja Google Chat przejdzie do innego okna lub zamknie okno, aby zakończyć interakcję.
Użytkownik zamyka okno 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 dialogów interaktywnych.

Odbieranie zdarzeń interakcji z aplikacją Google Chat

W tej sekcji dowiesz się, jak odbierać i przetwarzać zdarzenia interakcji z aplikacją Google Chat.

Skonfiguruj aplikację do obsługi czatu, aby otrzymywać zdarzenia 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 Architektura implementacji aplikacji Google Chat.

W przypadku każdej z funkcji interaktywnych, które chcesz utworzyć, musisz zaktualizować konfigurację w interfejsie Chat API, aby umożliwić wysyłanie powiązanych zdarzeń interakcji do Twojej aplikacji Google Chat:

1. W konsoli Google Cloud otwórz stronę interfejsu API czatu i kliknij 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. Zestaw pól, które określają, jak aplikacja Google Chat 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: 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 wdraża aplikację Google Chat. Nazwa tematu Cloud Pub/Sub: temat Pub/Sub, do którego aplikacja do obsługi czatu subskrybuje jako punkt końcowy. Dialogflow rejestruje aplikację Google Chat przy użyciu integracji 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ą być wyświetlane użytkownikom w Google Chat. Umożliwia użytkownikom wyświetlanie podstawowych działań w aplikacji Google Chat i wybranie konkretnego działania, z którym chcą się komunikować. 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 artykule 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 ponownych prób wywołania HTTP do usługi

Jeśli żądanie HTTPS do Twojej usługi zakończy się niepowodzeniem (np. z powodu przekroczenia limitu czasu, tymczasowej awarii sieci lub kodu stanu HTTPS innego niż 2xx), Google Chat może kilkakrotnie w ciągu kilku minut podjąć kolejną próbę dostarczenia danych (ale nie jest to gwarantowane). W wyniku tego w niektórych sytuacjach aplikacja Google Chat może otrzymać tę samą wiadomość kilka razy. 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 odpowiadanie na nie

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

Gdy aplikacja Google Chat otrzyma zdarzenie interakcji z Google Chat, może na nie zareagować na wiele sposobów. W wielu przypadkach interaktywne aplikacje do czatu odpowiadają użytkownikowi wiadomością. Aplikacja Google Chat może też wyszukiwać informacje w źródle danych, rejestrować informacje o zdarzeniu interakcji lub po prostu 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ą 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 pozwalają aplikacjom Google Chat odpowiadać w czasie rzeczywistym lub synchronicznie. Odpowiedzi synchroniczne 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ć ich z innymi typami odpowiedzi, zapoznaj się z tymi przewodnikami:

• Otwieranie interaktywnych dialogów
• 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 wiadomość tekstową za każdym razem, gdy zostanie dodana 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ć wiadomość tekstową, gdy użytkownik doda Twoją aplikację do obsługi czatu do pokoju, aplikacja ta odpowiada na ADDED_TO_SPACE zdarzenie interakcji. 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:

Odpowiedź asynchroniczna

Czasami aplikacje czatu muszą odpowiedzieć na zdarzenie interakcji po 30 sekundach lub wykonać zadania poza pokojem, w którym zostało wygenerowane zdarzenie interakcji. 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 artykułem Tworzenie wiadomości. Więcej informacji o dodatkowych metodach interfejsu Chat API znajdziesz w artykule Omówienie interfejsu Chat API.

Powiązane artykuły

• Wyślij wiadomość
• Otwieranie interaktywnych dialogów
• Linki do podglądu
• Czytanie danych z formularzy wprowadzonych przez użytkowników na kartach
• Odpowiadanie na polecenia z ukośnikiem
• Tworzenie strony głównej aplikacji Google Chat
• Weryfikowanie żądań z Google Chat
• Testowanie funkcji interaktywnych w aplikacjach Google Chat