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, przeczytaj artykuł Otrzymywanie interakcji z aplikacją do obsługi czatu i reagowanie na nie.

Formaty zdarzeń interakcji

Użytkownicy mogą korzystać z aplikacji do obsługi czatu 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 dodał Twoją aplikację Google Chat do pokoju.
  • Usunięto z pokoju: użytkownik usuwa z pokoju Twoją aplikację Google Chat.
  • Kliknięta karta: użytkownik klika interaktywną kartę lub okno dialogowe wysłane przez Twoją aplikację do obsługi czatu.

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, która jest ładunkiem JSON reprezentującym tę interakcję. Zawiera on 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 Event dotyczącej interfejsu Google Chat API.

Wspólne pola

W ładunku zdarzenia interakcji zawsze są podawane 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ść związana ze zdarzeniem. 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 związany ze zdarzeniem. Użytkownik jest zawsze osobą (a nie aplikacją do Google Chat). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Funkcja wywoływana przez użytkownika, gdy kliknie interaktywną kartę lub okno. CARD_CLICKED.

Przykładowe ładunki zdarzeń

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

przekaz,

To zdarzenie interakcji występuje, gdy użytkownik wysyła wiadomość do aplikacji Google Chat, na przykład:

  • każdej wiadomości na czacie z aplikacją Google Chat.
  • wiadomość w pokoju wieloosobowym, w której użytkownik dodał @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 opublikuje wiadomość zawierającą link zgodny ze skonfigurowanym wzorcem adresu URL.

Poniższy przykład JSON przedstawia zdarzenie interakcji MESSAGE, w którym użytkownik @wzmiankę o aplikacji do obsługi czatu 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 Twoja aplikacja do obsługi czatu została dodana do pokoju. Aplikacje zwykle reagują na to zdarzenie interakcji, publikując wiadomość powitalną w nowym wątku w pokoju.

Ten przykładowy kod JSON pokazuje treść żądania zdarzenia interakcji ADDED_TO_SPACE, gdy użytkownik doda do pokoju aplikację do obsługi czatu:

{
  "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ż oznaczać, że administrator Google Workspace zainstalował Twoją aplikację Google Chat dla użytkownika w organizacji.

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

Ten przykładowy kod JSON pokazuje 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 Twoja aplikacja do obsługi czatu 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 usunie 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ł Twoją aplikację Google Chat u użytkownika w organizacji. Po odinstalowaniu aplikacja do obsługi czatu przestanie być widoczna w panelu czatu użytkownika.

Jeśli użytkownik zainstalował Twoją aplikację do obsługi czatu przed dostępem administratora, aplikacja ta pozostanie zainstalowana dla użytkownika. 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 odinstaluje 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 odebrać 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 otwierający link do witryny, ale w poniższych przykładach otrzymuje 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 użytkownik klika przycisk Submit.

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

{
  "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 wchodzi w interakcję z oknem, ładunek zdarzenia interakcji CARD_CLICKED zawiera te dodatkowe pola:

  • isDialogEvent: ustaw wartość true w przypadku zdarzeń interakcji, które obejmują okna.
  • DialogEventType: typ interakcji z oknem, np. czy użytkownik otwiera, przesyła lub anuluje okno.

Ten przykładowy kod 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: