Types of Google Chat app interaction events

This page describes the types of interaction events that your Google Chat app can receive from Google Chat.

To configure your Chat app to receive interaction events, see Receive and respond to interactions with your Chat app.

Formats for interaction events

Users can interact with Chat apps in many ways. For each type of interaction, Google Chat sends a different type of interaction event:

  • Message: A user sends your Chat app a message, or invokes your Chat app in a space.
  • Added to space: A user adds your Chat app to a space.
  • Removed from space: A user removes your Chat app from a space.
  • Card clicked: A user clicks an interactive card or dialog sent by your Chat app.

Each time a user interacts with your Chat app, Google Chat sends an interaction event with a request body, which is a JSON payload that represents the interaction. This event payload contains elements that are common to all types of interaction events, as well as elements that are specific to the event type.

To learn more about the fields in an interaction event, see the Google Chat API's Event reference documentation.

Common fields

The following fields are always provided in the payload of an interaction event:

Field Description
type The type of the event the Chat app is receiving, such as MESSAGE or ADDED_TO_SPACE.
eventTime The timestamp indicating when the event was dispatched.
common Represents information about the user's client, such as the locale or platform.

Fields by interaction event type

Depending on the event type, the payload might contain the following additional fields:

Field Description Event type
message The message related to the event. MESSAGE, ADDED_TO_SPACE, CARD_CLICKED.
space The space related to the event. MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
user The user related to the event. The user is always a person (not a Chat app). MESSAGE, ADDED_TO_SPACE, REMOVED_FROM_SPACE, CARD_CLICKED.
action The function that a user triggers when they click an interactive card or dialog. CARD_CLICKED.

Example event payloads

This section describes what triggers an interaction event and provides an example JSON payload for each of the following event types:

Message

This interaction event represents when a person sends a message to the Chat app, such as:

  • Any message in a direct message (DM) space with the Chat app.
  • A message in a multi-person space where a person @mentions the Chat app, or uses one of its slash commands.
  • If you've configured link previews for your Chat app, a user posts a message that contains a link that matches the configured URL pattern.

The following JSON example shows a MESSAGE interaction event where a user @mentions a Chat app in a space with multiple people:

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

Added to space

This interaction event indicates that your Chat app was added to a space. Apps typically respond to this interaction event by posting some kind of welcome message in a new thread in the space.

The following JSON example shows the request body for an ADDED_TO_SPACE interaction event when a user adds a Chat app to a space:

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

Installed by Google Workspace administrators

The ADDED_TO_SPACE interaction event can also indicate that a Google Workspace administrator has installed your Chat app for a user in their organization.

Administrators can only install a Chat app for direct messages between the Chat app and the user. The installed app appears in the users' direct message panel. When administrators install Chat apps, users can't uninstall them. To learn about Chat apps installed by administrators, see Google Workspace Admin Help's documentation, Install Marketplace apps in your domain.

The following JSON example shows the request body for an ADDED_TO_SPACE interaction event when a Google Workspace administrator installs a Chat app for a user. Since an administrator installed the Chat app, adminInstalled is set to 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"
  }
}

Removed from space

This interaction event indicates that your Chat app was removed from a space. Chat apps don't respond with messages to this event, because they have already been removed.

The following JSON example shows the request body for an REMOVED_FROM_SPACE interaction event when a user removes a Chat app from a space:

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

Uninstalled by Google Workspace administrators

The REMOVED_FROM_SPACE interaction event can also indicate that a Google Workspace administrator uninstalled your Chat app for a user in their organization. When uninstalled, the Chat app no longer appears in the user's direct message panel.

If a user installed your Chat app before the administrator, the Chat app remains installed for the user. In this case, since the Chat app is still installed, the Chat app doesn't receive a REMOVED_FROM_SPACE interaction event.

The following JSON example shows the request body for a REMOVED_FROM_SPACE interaction event when a Google Workspace administrator uninstalls a Chat app for a user. Since the Chat app was uninstalled by an administrator, adminInstalled is set to 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"
  }
}

Card clicked

This interaction event indicates that a user clicked a button in a card message or dialog.

To receive an interaction event, the button must trigger another interaction with the Chat app. For example, a Chat app doesn't receive a CARD_CLICKED interaction event if a user clicks a button that opens a link to a website, but receives interaction events in the following examples:

  • The user clicks a Send feedback button on a card, which opens a dialog for the user to input information.
  • The user clicks a Submit button after inputting information into a card or dialog.

The following JSON example shows the request body for a CARD_CLICKED interaction event when a user clicks a button in a card message that assigns an incoming support ticket to them:

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

Card clicks for dialogs

When a user interacts with a dialog, the payload for the CARD_CLICKED interaction event includes the following additional fields:

  • isDialogEvent: Set to true for interaction events that involve dialogs.
  • DialogEventType: The type of interaction with the dialog, including if a user opens, submits, or cancels a dialog.

The following JSON example shows a portion of a request body for a CARD_CLICKED interaction event. In this example, the user has clicked a button in a dialog that submits information to the Chat app:

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

To learn how to process the payloads of interaction events and return a response, see the following guides: