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 專用應用程式時，使用者無法解除安裝。如要瞭解管理員安裝的 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 應用程式已從聊天室中移除。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",
}

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