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