Arten von App-Interaktionsereignissen in Google Chat

Auf dieser Seite werden die Arten von Interaktionsereignissen beschrieben, die Ihre Google Chat-App von Google Chat empfangen kann.

Wie Sie die Chat-App für den Empfang von Interaktionsereignissen konfigurieren, erfahren Sie unter Interaktionen mit der Chat-App empfangen und beantworten.

Formate für Interaktionsereignisse

Nutzer haben verschiedene Möglichkeiten, mit Chat-Apps zu interagieren. Für jede Art von Interaktion sendet Google Chat eine andere Art von Interaktionsereignis:

  • Nachricht:Ein Nutzer sendet Ihrer Chat-App eine Nachricht oder ruft die Chat-App in einem Gruppenbereich auf.
  • Dem Gruppenbereich hinzugefügt:Ein Nutzer fügt Ihre Chat-App einem Gruppenbereich hinzu.
  • Aus Gruppenbereich entfernt:Ein Nutzer entfernt Ihre Chat-App aus einem Gruppenbereich.
  • Karte angeklickt:Ein Nutzer klickt auf eine interaktive Karte oder ein Dialogfeld, das von Ihrer Chat-App gesendet wurde.

Jedes Mal, wenn ein Nutzer mit Ihrer Chat-App interagiert, sendet Google Chat ein Interaktionsereignis mit einem Anfragetext. Das ist eine JSON-Nutzlast, die die Interaktion darstellt. Diese Ereignisnutzlast enthält Elemente, die allen Arten von Interaktionsereignissen gemeinsam sind, sowie Elemente, die für den Ereignistyp spezifisch sind.

Weitere Informationen zu den Feldern in einem Interaktionsereignis finden Sie in der Event-Referenzdokumentation der Google Chat API.

Gemeinsam verwendete Felder

Die folgenden Felder werden immer in der Nutzlast eines Interaktionsereignisses bereitgestellt:

Field Beschreibung
type Der Typ des Ereignisses, das die Chat-App empfängt, z. B. MESSAGE oder ADDED_TO_SPACE.
eventTime Der Zeitstempel, der angibt, wann das Ereignis ausgelöst wurde.
common Informationen zum Client des Nutzers, z. B. Sprache oder Plattform.

Felder nach Interaktionsereignistyp

Je nach Ereignistyp kann die Nutzlast die folgenden zusätzlichen Felder enthalten:

Field Beschreibung Ereignistyp
message Die zum Ereignis gehörige Nachricht. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space Der zur Veranstaltung gehörige Raum. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user Der Nutzer, der sich auf das Ereignis bezieht. Der Nutzer ist immer eine Person (keine Chat-App). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action Die Funktion, die ein Nutzer auslöst, wenn er auf eine interaktive Karte oder ein interaktives Dialogfeld klickt. CARD_CLICKED.

Beispiel für Ereignisnutzlasten

In diesem Abschnitt wird beschrieben, was ein Interaktionsereignis auslöst. Außerdem finden Sie für jeden der folgenden Ereignistypen eine JSON-Beispielnutzlast:

die Botschaft und

Dieses Interaktionsereignis bedeutet, dass eine Person eine Nachricht an die Chat-App sendet, z. B.:

  • Alle Nachrichten in einem Direktnachrichten-Bereich mit der Google Chat App.
  • Eine Nachricht in einem Gruppenbereich mit mehreren Personen, in dem eine Person die Chat-App @erwähnt oder einen der Slash-Befehle verwendet.
  • Wenn Sie Linkvorschauen für Ihre Chat-App konfiguriert haben, postet ein Nutzer eine Nachricht mit einem Link, der mit dem konfigurierten URL-Muster übereinstimmt.

Das folgende JSON-Beispiel zeigt ein MESSAGE-Interaktionsereignis, bei dem ein Nutzer eine Chat-App in einem Gruppenbereich mit mehreren Personen @erwähnt:

{
  "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"
  }
}

Dem Gruppenbereich hinzugefügt

Dieses Interaktionsereignis zeigt an, dass Ihre Chat-App einem Gruppenbereich hinzugefügt wurde. Apps reagieren normalerweise auf dieses Interaktionsereignis, indem sie eine Art Willkommensnachricht in einem neuen Thread im Gruppenbereich posten.

Das folgende JSON-Beispiel zeigt den Anfragetext für ein ADDED_TO_SPACE-Interaktionsereignis, wenn ein Nutzer einem Gruppenbereich eine Chat-App hinzufügt:

{
  "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"
  }
}

Von Google Workspace-Administratoren installiert

Das Interaktionsereignis ADDED_TO_SPACE kann auch anzeigen, dass ein Google Workspace-Administrator Ihre Chat-App für einen Nutzer in seiner Organisation installiert hat.

Administratoren können eine Chat-App nur für Direktnachrichten zwischen der Chat-App und dem Nutzer installieren. Die installierte Anwendung wird im Bereich für Direktnachrichten des Nutzers angezeigt. Wenn Administratoren Chat-Apps installieren, können Nutzer sie nicht deinstallieren. Weitere Informationen zu Chat-Apps, die von Administratoren installiert wurden, finden Sie in der Hilfe für Google Workspace-Administratoren unter Marketplace-Apps in Ihrer Domain installieren.

Das folgende JSON-Beispiel zeigt den Anfragetext für ein ADDED_TO_SPACE-Interaktionsereignis, wenn ein Google Workspace-Administrator eine Chat-App für einen Nutzer installiert. Da ein Administrator die Chat-App installiert hat, ist adminInstalled auf true festgelegt:

{
  "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"
  }
}

Aus Gruppenbereich entfernt

Dieses Interaktionsereignis zeigt an, dass Ihre Chat-App aus einem Gruppenbereich entfernt wurde. Chat-Apps antworten nicht mit Nachrichten auf diesen Termin, da sie bereits entfernt wurden.

Das folgende JSON-Beispiel zeigt den Anfragetext für ein REMOVED_FROM_SPACE-Interaktionsereignis, wenn ein Nutzer eine Chat-App aus einem Gruppenbereich entfernt:

{
  "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"
  }
}

Von Google Workspace-Administratoren deinstalliert

Das Interaktionsereignis REMOVED_FROM_SPACE kann auch darauf hinweisen, dass ein Google Workspace-Administrator Ihre Chat-App für einen Nutzer in seiner Organisation deinstalliert hat. Nach der Deinstallation wird die Chat-App nicht mehr im Bereich für Direktnachrichten des Nutzers angezeigt.

Wenn ein Nutzer die Chat-App vor dem Administrator installiert hat, bleibt die Chat-App für ihn installiert. Da die Chat-App noch installiert ist, empfängt sie in diesem Fall kein REMOVED_FROM_SPACE-Interaktionsereignis.

Das folgende JSON-Beispiel zeigt den Anfragetext für ein REMOVED_FROM_SPACE-Interaktionsereignis, wenn ein Google Workspace-Administrator eine Chat-App für einen Nutzer deinstalliert. Da die Chat-App von einem Administrator deinstalliert wurde, ist adminInstalled auf true festgelegt:

{
  "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"
  }
}

Karte angeklickt

Dieses Interaktionsereignis zeigt an, dass ein Nutzer auf eine Schaltfläche in einer Kartennachricht oder einem Dialogfeld geklickt hat.

Damit ein Interaktionsereignis empfangen werden kann, muss die Schaltfläche eine weitere Interaktion mit der Chat-App auslösen. Eine Chat-App empfängt beispielsweise kein CARD_CLICKED-Interaktionsereignis, wenn ein Nutzer auf eine Schaltfläche klickt, über die ein Link zu einer Website geöffnet wird. In den folgenden Beispielen wird dafür ein Interaktionsereignis erfasst:

  • Der Nutzer klickt auf einer Karte auf die Schaltfläche Send feedback, wodurch ein Dialogfeld zur Eingabe von Informationen geöffnet wird.
  • Der Nutzer klickt auf eine Submit-Schaltfläche, nachdem er Informationen in eine Karte oder ein Dialogfeld eingegeben hat.

Das folgende JSON-Beispiel zeigt den Anfragetext für ein CARD_CLICKED-Interaktionsereignis, wenn ein Nutzer auf eine Schaltfläche in einer Kartennachricht klickt, die ihm ein eingehendes Support-Ticket zuweist:

{
  "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
  }
}

Klicks auf die Karte für Dialogfelder

Wenn ein Nutzer mit einem Dialogfeld interagiert, enthält die Nutzlast für das Interaktionsereignis CARD_CLICKED die folgenden zusätzlichen Felder:

  • isDialogEvent: Legen Sie diesen Wert für Interaktionsereignisse, die Dialoge umfassen, auf true fest.
  • DialogEventType: Die Art der Interaktion mit dem Dialogfeld, z. B. ob ein Nutzer ein Dialogfeld öffnet, sendet oder abbricht.

Das folgende JSON-Beispiel zeigt einen Teil des Anfragetexts für ein CARD_CLICKED-Interaktionsereignis. In diesem Beispiel hat der Nutzer in einem Dialogfeld auf eine Schaltfläche geklickt, über die Informationen an die Chat-App gesendet werden:

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

In den folgenden Anleitungen erfahren Sie, wie Sie die Nutzlasten von Interaktionsereignissen verarbeiten und eine Antwort zurückgeben: