Otrzymuj interakcje użytkowników i reaguj na nie

Na tej stronie opisujemy, jak aplikacja Google Chat może odbierać i odpowiadać na interakcje użytkowników, czyli zdarzenia interakcji z aplikacją Google Chat.

Na tej stronie dowiesz się, jak:

  • Skonfiguruj aplikację Google Chat tak, aby odbierała zdarzenia interakcji.
  • Przetwarzanie zdarzenia interakcji w Twojej infrastrukturze.
  • W razie potrzeby reaguj na zdarzenia interakcji.

Wymagania wstępne

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 wchodzenie z nią w interakcję, na przykład @wywołanie aplikacji Google Chat lub dodanie jej do pokoju.

Gdy użytkownicy wchodzą w interakcję z aplikacją Google Chat, Google Chat wysyła do niej zdarzenie interakcji, reprezentowane w interfejsie API Google Chat 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 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 odezwać się z wiadomością powitalną w pokoju.

Aplikacja do czatu publikuje wiadomość powitalną.
Rysunek 1. Gdy użytkownik dodaje do pokoju aplikację Google Chat, ta otrzymuje zdarzenie interakcji ADDED_TO_SPACE, które obsługuje, aby wysłać wiadomość 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ą:

Interakcja użytkownika eventType Typowa odpowiedź z aplikacji Google Chat
Użytkownik wysyła wiadomość do aplikacji Google Chat. Na przykład: @wzmiankuje aplikację Google Chat lub używa polecenia po ukośniku. MESSAGE Aplikacja Google Chat odpowiada na podstawie treści wiadomości. Na przykład aplikacja Google Chat odpowiada na polecenie po ukośniku /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 Czat usuwa wszystkie przychodzące powiadomienia skonfigurowane dla pokoju (np. usuwanie webhook) i czyści pamięć wewnętrzną.
Użytkownik klika przycisk na karcie z poziomu wiadomości, okna dialogowego lub strony głównej 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 Chat. SUBMIT_FORM Aplikacja Google 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 Google Chat odpowiada na podstawie wywołanego polecenia. Na przykład aplikacja Google Chat odpowiada na polecenie O mnie wiadomością, która wyjaśnia, jakie zadania może wykonywać.

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

Zdarzenia interakcji z dialogami

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ń dialogowych oraz o tym, jak aplikacje do czatu zwykle reagują:

Interakcja użytkownika z oknem dialogowym Typ zdarzenia dialogowego Typowa odpowiedź
Użytkownik uruchamia prośbę o wyświetlenie okna. Może to być na przykład użycie polecenia / lub kliknięcie przycisku 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

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 Google Chat 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 utworzyć:

    Pole Opis
    Funkcjonalność Wymagane. Zestaw pól, które określają, jak aplikacja Google Chat może wchodzić w interakcje z użytkownikami:
    • Otrzymywanie 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 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 Google Chat 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 Opcjonalnie. Polecenia po ukośniku i szybkie polecenia w aplikacji Google Chat. Polecenia umożliwiają użytkownikom wykonywanie określonych działań lub korzystanie z określonych funkcji aplikacji Google Chat. Więcej informacji znajdziesz w artykule Odpowiedzi 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. 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 do odbierania zdarzeń 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 ponownie próbować wysłać dane (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 Google Chat mogą przetwarzać zdarzenia interakcji i odpowiadać na nie.

Gdy aplikacja Google Chat otrzyma zdarzenie interakcji z Google Chat, może na nie odpowiedzieć 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 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 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 do przetworzenia odpowiedzi. 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:

Architektura przetwarzania zdarzeń interakcji przez aplikacje Google Chat

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:

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 Google Chat 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 następujący SMS:

Przykładowy komunikat wprowadzający

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. Na przykład aplikacja do obsługi czatu może potrzebować odpowiedzi na wiadomość od 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, zapoznaj się z artykułem Tworzenie wiadomości. Informacje o używaniu dodatkowych metod interfejsu Chat API znajdziesz w artykule Omówienie interfejsu Chat API.