Event formats

This section describes the format of events that your app receives from Google Chat.

Event fields

When your app receives an event from Google Chat, the event includes a request body: this is the JSON payload that represents the event. This payload contains elements that are common to all event types, as well as elements that are specific to the event type. The following diagram shows the fields that might be present in the payload:

Fields present in a request body.

Common event fields

Common fields are always provided in the payload of all events, regardless of type.

Field	Type	Description
`type`	String	The type of the event the app is receiving.
`eventTime`	String	The timestamp (formatted according to RFC 3339) indicating when the event was dispatched.

Type-specific event fields

Additional fields might be present in the request payload, if they are applicable to the event type.

Field	Type	Description	Event type
`message`	Message	The message related to the event.	Message, added to space.
`space`	Space	The space related to the event.	Message, added to space, removed from space.
`user`	User	The user related to the event.	Message, added to space, removed from space.
`thread`	Thread	The thread a message belongs to.	Message events only.

Event types

This section describes the types of events that your app might receive, with examples of each type.

`MESSAGE`

This event represents a message sent to the app.

The message details are stored as fields within the message field. Response behavior: posts a message in the same thread as the original user message.

An example payload:

{
  "type": "MESSAGE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "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": "2017-03-02T19:02:59.910959Z",
    "text": "@TestBot Create ticket.",
    "argumentText": " Create ticket.",
    "thread": {
      "name": "spaces/AAAAAAAAAAA/threads/BBBBBBBBBBB"
    },
    "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 event indicates that your app was added to a space. Apps typically respond to this 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 event when a user adds a Chat app to a space:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "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 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 app and the user. The installed app appears in the users’ direct message panel. Users cannot uninstall apps that were installed by their administrator. 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 event when a Google Workspace administrator installs a Chat app for a user. Since the app was installed by an administrator, adminInstalled is set to true:

{
  "type": "ADDED_TO_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "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 event indicates that your app was removed from a space. Apps don't respond to this event, because they have already been removed.

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

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "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 event can also indicate that a Google Workspace administrator uninstalled your Chat app for a user in their organization. When uninstalled, the app no longer appears in the user’s direct message panel.

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

The following JSON example shows the request body for a REMOVED_FROM_SPACE event when a Google Workspace administrator uninstalls a Chat app for a user. Since the app was uninstalled by an administrator, adminInstalled is set to true:

{
  "type": "REMOVED_FROM_SPACE",
  "eventTime": "2017-03-02T19:02:59.910959Z",
  "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"
  }
}