Otrzymuj interakcje użytkowników i reaguj na nie

Na tej stronie opisujemy, jak aplikacja Google Chat może odbierać interakcje użytkowników i na nie odpowiadać. Takie interakcje nazywamy 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.

Tworzenie interaktywnej aplikacji Google Chat jako dodatku do Google Workspace

Aby utworzyć aplikację Google Chat, która będzie wchodzić w interakcje z użytkownikami czatu, możesz utworzyć dodatek Google Workspace, który rozszerzy możliwości czatu. Zamiast otrzymywać zdarzenia interakcji z interfejsu API Google Chat, aplikacja Google Chat otrzymuje obiekty zdarzeń dodatku i odpowiada na nie. Więcej informacji znajdziesz w sekcji Rozszerzanie Google Chat w dokumentacji dodatku Google Workspace.

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 w Google Cloud Functions
• Google Apps Script
• Google Cloud Dialogflow CX
• Google Cloud Pub/Sub

Typy zdarzeń interakcji

Zdarzenie interakcji z aplikacją Google Chat to każde działanie użytkownika, które powoduje wywołanie aplikacji Google Chat lub jej użycie, np. @wywołanie aplikacji Google Chat lub dodanie jej do przestrzeni.

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 wykorzystać to zdarzenie do przetworzenia interakcji i opcjonalnie odpowiedzieć 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 typu zdarzenia ADDED_TO_SPACE w przypadku każdej interakcji, w której użytkownik dodaje aplikację Google Chat do pokoju, aby aplikacja Google Chat mogła natychmiast odpowiedzieć wiadomością powitalną w pokoju.

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

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ó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 informacje o typowych interakcjach z dialogami, odpowiadających im typach zdarzeń dialogu oraz o tym, jak aplikacje do czatu zwykle na nie reagują:

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ć wychodzące wiadomości 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 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ę 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 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, 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 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ą 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ę zapoznać. 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.

Twoja 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 żą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ąć ponowną 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

Ta sekcja wyjaśnia, jak aplikacje Google Chat mogą przetwarzać zdarzenia interakcji i odpowiadać 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 umożliwiają aplikacjom czatu reagowanie w czasie rzeczywistym lub synchronicznie. Odpowiedzi synchroniczne nie wymagają uwierzytelniania.

Aby odpowiedzieć w czasie rzeczywistym, aplikacja Google Chat musi zwrócić obiekt Message. Aby odpwiedzieć 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 dialogów
• Linki do podglądu
• Procesowanie informacji przesyłanych przez użytkowników

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:

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

/**
 * 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 następujący SMS:

Odpowiedź asynchroniczna

Czasami aplikacje czatu muszą odpowiedzieć na zdarzenie interakcji po 30 sekundach lub wykonać zadania poza pokojem, w którym zostało wygenerowane to zdarzenie. 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