Rodzaje zdarzeń interakcji z aplikacją Google Chat

Na tej stronie opisujemy typy interakcji, które aplikacja Google Chat może odbierać z Google Chat.

Aby skonfigurować otrzymywanie zdarzeń interakcji w aplikacji do obsługi czatu, zapoznaj się z artykułem Odbieranie interakcji z aplikacją Google Chat i reagowanie na nie.

Formaty zdarzeń interakcji

Użytkownicy mogą korzystać z aplikacji Google Chat na wiele sposobów. W przypadku każdego typu interakcji Google Chat wysyła inny typ zdarzenia interakcji:

  • Wiadomość: użytkownik wysyła wiadomość do aplikacji Google Chat lub wywołuje ją w pokoju.
  • Dodano do pokoju: użytkownik dodaje Twoją aplikację Google Chat do pokoju.
  • Usunięto z pokoju:użytkownik usunął Twoją aplikację Google Chat z pokoju.
  • Kliknięto kartę: użytkownik klika interaktywną kartę lub okno dialogowe przesłane przez aplikację Google Chat.

Za każdym razem, gdy użytkownik wchodzi w interakcję z Twoją aplikacją do obsługi czatu, Google Chat wysyła zdarzenie interakcji z treścią żądania, czyli ładunkiem JSON reprezentującym tę interakcję. Ten ładunek zdarzenia zawiera elementy wspólne dla wszystkich typów zdarzeń interakcji oraz elementy charakterystyczne dla danego typu zdarzenia.

Więcej informacji o polach w zdarzeniu interakcji znajdziesz w dokumentacji referencyjnej interfejsu Event interfejsu Google Chat API.

Wspólne pola

W ładunku zdarzenia interakcji zawsze znajdują się te pola:

Pole Opis
type Typ zdarzenia odbieranego przez aplikację Google Chat, na przykład MESSAGE lub ADDED_TO_SPACE.
eventTime Sygnatura czasowa wskazująca, kiedy zdarzenie zostało wysłane.
common Przedstawia informacje o kliencie użytkownika, np. język lub platformę.

Pola według typu zdarzenia interakcji

W zależności od typu zdarzenia ładunek może zawierać te dodatkowe pola:

Pole Opis Typ zdarzenia
message Wiadomość dotycząca zdarzenia. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Pokój powiązany ze zdarzeniem. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user Użytkownik powiązany ze zdarzeniem. Użytkownik zawsze jest osobą (a nie aplikacją do obsługi czatu). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Funkcja wywoływana przez użytkownika, gdy klika interaktywną kartę lub okno. CARD_CLICKED.

Przykładowe ładunki zdarzeń

W tej sekcji opisujemy, co wyzwala zdarzenie interakcji, oraz podajemy przykładowy ładunek JSON dla każdego z tych typów zdarzeń:

przekaz,

To zdarzenie interakcji informuje o wysłaniu przez użytkownika wiadomości do aplikacji Google Chat, na przykład:

  • dowolnej wiadomości na czacie z aplikacją Google Chat,
  • Wiadomość w pokoju wieloosobowym, w którym ktoś dodaje @wzmiankę o aplikacji Google Chat lub używa jednego z poleceń po ukośniku.
  • Jeśli masz skonfigurowany podgląd linków w aplikacji Google Chat, użytkownik publikuje wiadomość zawierającą link zgodny ze skonfigurowanym wzorcem adresu URL.

Ten przykład JSON pokazuje zdarzenie interakcji MESSAGE, w którym użytkownik @wzmiankę o aplikacji Google Chat w pokoju z wieloma osobami:

{
  "type": "MESSAGE",
  "eventTime": {
      "seconds": 1691187414,
      "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE"
  },
  "message": {
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "sender": {
      "name": "users/12345678901234567890",
      "displayName": "Izumi",
      "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
      "email": "izumi@example.com"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB",
      "threadKey": "custom-thread-ID"
    },
    "annotations": [
      {
        "length": 8,
        "startIndex": 0,
        "userMention": {
          "type": "MENTION",
          "user": {
            "avatarUrl": "https://.../avatar.png",
            "displayName": "TestBot",
            "name": "users/1234567890987654321",
            "type": "BOT"
          }
        },
        "type": "USER_MENTION"
      }
    ],
    "attachment": [
      {
        "name": "spaces/5o6pDgAAAAE/messages/Ohu1LlUVcS8.Ohu1LlUVcS8/attachments/AATUf-Iz7d8kySEdRRZd-dznqBk3",
        "content_name": "solar.png",
        "content_type": "image/png",
        "drive_data_ref": {
          "drive_file_id": "H1HqaqRuH2Pfd_TOa1fF2_ltwDlV_yKRrr"
        },
        "source": "DRIVE_FILE"
      }
    ]
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Dodano do pokoju

To zdarzenie interakcji wskazuje, że aplikacja Google Chat została dodana do pokoju. Aplikacje zwykle reagują na to zdarzenie, publikując wiadomość powitalną w nowym wątku.

Ten przykładowy kod JSON pokazuje treść żądania zdarzenia interakcji ADDED_TO_SPACE, gdy użytkownik dodaje do pokoju aplikację Google Chat:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Zainstalowane przez administratorów Google Workspace

Zdarzenie interakcji ADDED_TO_SPACE może też wskazywać, że administrator Google Workspace zainstalował Twoją aplikację Google Chat dla użytkownika w organizacji.

Administratorzy mogą zainstalować aplikację Google Chat tylko do czatów indywidualnych między aplikacją Google Chat a użytkownikiem. Zainstalowana aplikacja pojawi się w panelu czatu użytkowników. Gdy administratorzy instalują aplikacje Google Chat, użytkownicy nie mogą ich odinstalować. Więcej informacji o aplikacjach do obsługi czatu zainstalowanych przez administratorów znajdziesz w artykule Instalowanie aplikacji z Marketplace w domenie w Centrum pomocy dla administratorów Google Workspace.

Ten przykładowy kod JSON przedstawia treść żądania zdarzenia interakcji ADDED_TO_SPACE, gdy administrator Google Workspace zainstaluje dla użytkownika aplikację Google Chat. Ponieważ administrator zainstalował aplikację Google Chat, ustawienie adminInstalled ma wartość true:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "displayName": "Customer Support Superstars",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Usunięto z pokoju

To zdarzenie interakcji wskazuje, że aplikacja Google Chat została usunięta z pokoju. Aplikacje do obsługi czatu nie odpowiadają na to zdarzenie, ponieważ zostały już usunięte.

Ten przykładowy kod JSON pokazuje treść żądania zdarzenia interakcji REMOVED_FROM_SPACE, gdy użytkownik usuwa z pokoju aplikację Google Chat:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "SPACE",
    "adminInstalled": "false"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Odinstalowana przez administratorów Google Workspace

Zdarzenie interakcji REMOVED_FROM_SPACE może też oznaczać, że administrator Google Workspace odinstalował aplikację Google Chat u użytkownika z jego organizacji. Po odinstalowaniu aplikacja do obsługi czatu zniknie z panelu czatu użytkownika.

Jeśli użytkownik zainstalował Twoją aplikację Google Chat przed administratorem, pozostanie ona zainstalowana u niego. W tym przypadku aplikacja Google Chat jest nadal zainstalowana, więc nie otrzyma zdarzenia interakcji REMOVED_FROM_SPACE.

Ten przykładowy kod JSON pokazuje treść żądania zdarzenia interakcji REMOVED_FROM_SPACE, gdy administrator Google Workspace odinstalowuje aplikację Google Chat dla użytkownika. Aplikacja Google Chat została odinstalowana przez administratora, więc ustawienie adminInstalled ma wartość true:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "space": {
    "name": "spaces/AAAAAAAAAAA",
    "spaceType": "DIRECT_MESSAGE",
    "adminInstalled": "true"
  },
  "user": {
    "name": "users/12345678901234567890",
    "displayName": "Izumi",
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "email": "izumi@example.com"
  }
}

Kliknięto kartę

To zdarzenie interakcji wskazuje, że użytkownik kliknął przycisk w komunikacie na karcie lub w oknie.

Aby otrzymać zdarzenie interakcji, przycisk musi wywołać kolejną interakcję z aplikacją Google Chat. Na przykład aplikacja Google Chat nie otrzyma zdarzenia interakcji CARD_CLICKED, jeśli użytkownik kliknie przycisk, który otwiera link do witryny, ale w tych przykładach odbiera zdarzenia interakcji:

  • Użytkownik klika na karcie przycisk Send feedback, co otwiera okno, w którym może wpisać informacje.
  • Po wpisaniu informacji na karcie lub w oknie dialogowym użytkownik klika przycisk Submit.

Ten przykładowy kod JSON pokazuje treść żądania zdarzenia interakcji CARD_CLICKED, gdy użytkownik kliknie przycisk w wiadomości na karcie, który przypisuje mu zgłoszenie do zespołu pomocy:

{
  "type": "CARD_CLICKED",
  "eventTime": {
    "seconds": 1691187414,
    "nanos": 93489000
  },
  "common": {
    "userLocale": "en",
    "hostApp": "CHAT",
    "invokedFunction": "doAssignTicket",
    "timeZone": {
      "offset": -25200000,
      "id": "America/Los_Angeles"
    }
  },
  "action": {
    "actionMethodName": "doAssignTicket"
  },
  "message": {
    "cards": [
      {
        "header": {
          "title": "Incoming support ticket."
        },
        "sections": [
          {
            "widgets": [
              {
                "textParagraph": {
                  "text": "Incoming support ticket #12345 is unassigned and needs your attention."
                }
              },
              {
                "buttons": [
                  {
                    "textButton": {
                      "onClick": {
                        "action": {
                          "actionMethodName": "doAssignTicket"
                        }
                      },
                      "text": "Assign to me"
                    }
                  }
                ]
              }
            ]
          }
        ]
      }
    ],
    "sender": {
      "avatarUrl": "https://www.example.com/images/chat-app-icon.png",
      "displayName": "Support Chat app",
      "name": "users/98765432109876543210",
      "type": "BOT"
    },
    "createTime": {
      "seconds": 1691187386,
      "nanos": 954319000
    },
    "retentionSettings": {
      "state": "PERMANENT"
    },
    "name": "spaces/AAAAAAAAAAA/messages/CCCCCCCCCCC",
    "thread": {
      "retentionSettings": {
        "state": "PERMANENT"
      },
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "messageHistoryState": "HISTORY_ON",
    "space": {
      "spaceThreadingState": "GROUPED_MESSAGES",
      "spaceType": "SPACE",
      "displayName": "Customer Support Superstars",
      "name": "spaces/AAAAAAAAAAA",
      "spaceHistoryState": "HISTORY_ON",
      "type": "ROOM",
      "threaded": true
    }
  },
  "user": {
    "avatarUrl": "https://lh3.googleusercontent.com/.../photo.jpg",
    "displayName": "Izumi",
    "name": "users/12345678901234567890",
    "type": "HUMAN",
    "email": "izumi@example.com",
    "domainId": "ABCDEFG"
  },
  "space": {
    "spaceThreadingState": "GROUPED_MESSAGES",
    "spaceType": "SPACE",
    "displayName": "Customer Support Superstars",
    "name": "spaces/AAAAAAAAAAA",
    "spaceHistoryState": "HISTORY_ON",
    "type": "ROOM",
    "threaded": true
  }
}

Kliknięcia karty w oknach

Gdy użytkownik wejdzie w interakcję z oknem, ładunek zdarzenia interakcji CARD_CLICKED będzie zawierał te dodatkowe pola:

  • isDialogEvent: ustaw wartość true w przypadku zdarzeń interakcji, które obejmują okna.
  • DialogEventType: typ interakcji z oknem, w tym otwarcie, przesłanie lub anulowanie okna przez użytkownika.

Poniższy przykład JSON pokazuje część treści żądania zdarzenia interakcji CARD_CLICKED. W tym przykładzie użytkownik kliknął przycisk w oknie, które przesyła informacje do aplikacji Google Chat:

{
  "type": "CARD_CLICKED",
  ...
  "isDialogEvent": true,
  "dialogEventType": "SUBMIT_DIALOG",
}

Aby dowiedzieć się, jak przetworzyć ładunki zdarzeń interakcji i zwrócić odpowiedź, zapoznaj się z tymi przewodnikami: