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 應用程式接收的事件類型，例如 MESSAGE 或 ADDED_TO_SPACE。
eventTime 時間戳記，表示傳送事件的時間。
common 代表使用者的用戶端資訊，例如語言代碼或平台。

按互動事件類型列出的欄位

視事件類型而定，酬載可能包含下列額外欄位：

欄位 說明 事件類型
message 與事件相關的訊息。 MESSAGE，ADDED_TO_SPACE，CARD_CLICKED。
space 與活動相關的聊天室。 MESSAGE，ADDED_TO_SPACE，REMOVED_FROM_SPACE，CARD_CLICKED。
user 與事件相關的使用者。使用者一律是個人 (而非 Chat 應用程式)。 MESSAGE，ADDED_TO_SPACE，REMOVED_FROM_SPACE，CARD_CLICKED。
action 使用者點選互動式資訊卡或對話方塊時觸發的函式。 CARD_CLICKED.

事件酬載範例

本節說明觸發互動事件的類型，並針對以下每種事件類型提供範例 JSON 酬載：

訊息

此互動事件代表使用者向 Chat 應用程式傳送訊息，例如：

  • 與 Chat 應用程式互傳的即時訊息 (DM) 聊天室中的任何訊息。
  • 在多人空間中，某位使用者使用 @號提及 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 專用應用程式時，使用者無法解除安裝。如要進一步瞭解管理員安裝的即時通訊應用程式，請參閱 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",
}

如要瞭解如何處理互動事件的酬載並傳回回應，請參閱下列指南：