Google Chat 应用互动事件类型

本页面介绍了 Google Chat 应用可以接收来自 Google Chat 的互动事件类型。

如要配置 Chat 应用以接收互动事件,请参阅接收和响应用户与 Chat 应用的互动

互动事件的格式

用户可以通过多种方式与 Chat 应用互动。对于每种类型的互动,Google Chat 都会发送不同类型的互动事件:

  • 消息:用户向您的 Chat 应用发送消息,或在聊天室中调用您的 Chat 应用。
  • 已添加到聊天室:用户将您的 Chat 应用添加到聊天室。
  • 已从聊天室中移除:用户将您的 Chat 应用从聊天室中移除。
  • 已点击卡片:用户点击您的 Chat 应用发送的互动卡片或对话框。

每当用户与您的 Chat 应用互动时,Google Chat 都会发送一个带有请求正文的互动事件,请求正文是一个表示互动的 JSON 载荷。此事件载荷包含所有类型的互动事件共有的元素,以及事件类型特有的元素。

如需详细了解互动事件中的字段,请参阅 Google Chat API 的 Event 参考文档

常用字段

互动事件的载荷中始终会提供以下字段:

字段 说明
type Chat 应用收到的事件的类型,例如 MESSAGEADDED_TO_SPACE
eventTime 指示事件分派时间的时间戳
common 表示有关用户客户端的信息,例如语言区域或平台。

按互动事件类型划分的字段

根据事件类型,载荷可能包含以下附加字段:

字段 说明 事件类型
message 与事件相关的消息。 MESSAGEADDED_TO_SPACECARD_CLICKED
space 与活动相关的聊天室。 MESSAGEADDED_TO_SPACEREMOVED_FROM_SPACECARD_CLICKED
user 与事件相关的用户。用户始终是真人(而非 Chat 应用)。 MESSAGEADDED_TO_SPACEREMOVED_FROM_SPACECARD_CLICKED
action 用户点击互动卡片或对话框时触发的函数。 CARD_CLICKED.

事件载荷示例

本部分介绍了触发互动事件的原因,并提供了以下每种事件类型的示例 JSON 载荷:

消息

此互动事件表示用户向 Chat 应用发送消息的情况,例如:

  • 私信 (DM) 聊天室中与 Chat 应用之间的任何消息。
  • 在多人聊天室中,用户用“@”提及 Chat 应用或使用该应用的某个斜杠命令。
  • 如果您为 Chat 应用配置了链接预览,用户就会发布一条消息,其中包含与配置的网址格式匹配的链接。

以下 JSON 示例展示了一个 MESSAGE 互动事件,用户用“@”提及一个有多人的聊天室中的 Chat 应用:

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

已添加到聊天室

此互动事件表示您的 Chat 应用已添加到聊天室。应用通常会通过在聊天室的新消息串中发布某种欢迎消息来响应此互动事件。

以下 JSON 示例显示了用户将 Chat 应用添加到聊天室时 ADDED_TO_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"
  }
}

由 Google Workspace 管理员安装

ADDED_TO_SPACE 互动事件还可以表示 Google Workspace 管理员为其组织中的用户安装了您的 Chat 应用。

管理员只能安装 Chat 应用,以便在 Chat 应用和用户之间收发私信。已安装的应用会显示在用户的私信面板中。管理员安装 Chat 应用后,用户无法卸载。如需了解管理员安装的 Chat 应用,请参阅 Google Workspace 管理员帮助文档:在您的网域中安装 Marketplace 中的应用

以下 JSON 示例显示了 Google Workspace 管理员为用户安装 Chat 应用时 ADDED_TO_SPACE 互动事件的请求正文。由于该 Chat 应用是由管理员安装的,因此 adminInstalled 设置为 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"
  }
}

已从聊天室中移出

此互动事件表示您的 Chat 应用已从聊天室中移除。聊天应用不会回复此事件的消息,因为它们已被移除。

以下 JSON 示例展示了当用户从聊天室中移除 Chat 应用时,REMOVED_FROM_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"
  }
}

Google Workspace 管理员已卸载

REMOVED_FROM_SPACE 互动事件还可能表示 Google Workspace 管理员为其组织中的用户卸载了您的 Chat 应用。卸载后,Chat 应用将不再显示在用户的私信面板中。

如果用户先于管理员安装了您的 Chat 应用,则 Chat 应用仍会保持安装状态。在这种情况下,由于 Chat 应用仍处于安装状态,因此 Chat 应用不会收到 REMOVED_FROM_SPACE 互动事件。

以下 JSON 示例显示了 Google Workspace 管理员为用户卸载 Chat 应用时 REMOVED_FROM_SPACE 互动事件的请求正文。由于管理员已卸载 Chat 应用,因此 adminInstalled 设置为 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"
  }
}

已点击卡片

此互动事件表示用户点击了卡片消息或对话框中的按钮。

如需接收互动事件,该按钮必须触发与 Chat 应用的另一互动。例如,在以下示例中,如果用户点击用于打开网站链接的按钮,Chat 应用不会收到 CARD_CLICKED 互动事件,但会收到互动事件:

  • 用户点击卡片上的 Send feedback 按钮,随即打开一个对话框,供用户输入信息。
  • 用户在卡片或对话框中输入信息后点击 Submit 按钮。

以下 JSON 示例展示了当用户点击卡片消息中的按钮(相应按钮可为其分配传入支持服务工单的按钮)时,CARD_CLICKED 互动事件的请求正文:

{
  "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_CLICKED 互动事件的载荷包含以下额外字段:

  • isDialogEvent:对于涉及对话框的互动事件,设置为 true
  • DialogEventType:与对话框的互动类型,包括用户是否打开、提交或取消对话框。

以下 JSON 示例显示了 CARD_CLICKED 互动事件的请求正文的一部分。在此示例中,用户点击了对话框中向 Chat 应用提交信息的按钮:

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

如需了解如何处理互动事件的载荷并返回响应,请参阅以下指南: