收集並處理 Google Chat 使用者的資訊

本指南將說明 Google Chat 應用程式如何收集及處理資訊 方便使用者直接在卡片式介面中建構表單輸入內容

對話方塊內含各種不同的小工具。
圖 1：A 範例 符合下列條件的即時通訊應用程式： 開啟對話方塊來收集聯絡資訊。

Chat 應用程式會向使用者索取資訊，以便在 Chat 中或在 Chat 之外執行動作，包括以下方式：

  • 調整設定。例如，讓使用者自訂通知設定，或將 Chat 應用程式新增至一或多個聊天室。
  • 在其他 Google Workspace 應用程式中建立或更新資訊。適用對象 讓使用者建立 Google 日曆活動。
  • 允許使用者存取及更新其他應用程式或網路服務中的資源。適用對象 例如 Chat 應用程式可以協助使用者 直接在 Chat 聊天室傳送的支援單狀態。

必要條件

已啟用互動功能的 Google Chat 應用程式。如要建立互動式 Chat 應用程式，請根據您要使用的應用程式架構，完成下列其中一個快速入門：

使用資訊卡建立表單

為了收集資訊，即時通訊應用程式設計表單和輸入內容： 並將資訊卡組合成資訊卡如要向使用者顯示資訊卡，Chat 應用程式可以使用下列 Chat 介面：

  • 含有一或多張資訊卡的訊息。
  • 首頁、 是直接從「首頁」分頁顯示的資訊卡 收發訊息。
  • 對話方塊，也就是開啟的資訊卡 開啟新分頁。

即時通訊應用程式可透過下列小工具建立資訊卡：

  • 可要求使用者提供資訊的表單輸入小工具。您可以視需要在表單輸入小工具中加入驗證，確保使用者正確輸入及格式化資訊。Chat 應用程式可以使用下列表單輸入小工具：

    • 文字輸入 (textInput) 表示任意形式或建議的文字。
    • 選取輸入來源 (selectionInput) 是可選取的 UI 元素，例如核取方塊、 圓形按鈕和下拉式選單選取輸入小工具也可以從靜態或動態資料來源填入項目。舉例來說，使用者可以 從清單中選取成員的 Chat 聊天室。
    • 日期和時間輸入項目的日期時間挑選器 (dateTimePicker)。

  • 按鈕小工具，方便使用者提交在資訊卡中輸入的值。使用者點選按鈕後，Chat 應用程式 處理接收的資訊。

以下內容顯示包含三種日期和資料類型的資訊卡 時間輸入：

如要進一步瞭解可用於收集資訊的互動式小工具，請參閱「設計互動式資訊卡或對話方塊」。

接收互動式小工具的資料

使用者只要按一下按鈕，即時通訊應用程式就會收到 CARD_CLICKED 互動事件 當中包含互動資訊CARD_CLICKED 互動事件的酬載包含 common.formInputs 物件，其中包含使用者輸入的任何值。

您可以擷取物件中的值 common.formInputs.WIDGET_NAME，其中 WIDGET_NAME 是您為小工具指定的 name 欄位。 這些值會傳回小工具的特定資料類型 (以 Inputs 物件)。 在以下範例中，資訊卡會使用文字輸入、日期時間挑選器和選取輸入小工具收集聯絡資訊：

{
  "textInput": {
    "name": "contactName",
    "label": "First and last name",
    "type": "SINGLE_LINE"
  }
}, {
  "dateTimePicker": {
    "name": "contactBirthdate",
    "label": "Birthdate",
    "type": "DATE_ONLY"
  }
}, {
  "selectionInput": {
    "name": "contactType",
    "label": "Contact type",
    "type": "RADIO_BUTTON",
    "items": [
      {
        "text": "Work",
        "value": "Work",
        "selected": false
      },
      {
        "text": "Personal",
        "value": "Personal",
        "selected": false
      }
    ]
  }
}

處理互動事件

當使用者在資訊卡或對話方塊中輸入資料時， Chat 應用程式收到 Chat 應用程式 CARD_CLICKED 互動事件，內含使用者輸入的值。

以下是 CARD_CLICKED 互動事件的部分內容，其中使用者輸入了每個小工具的值：

HTTP

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

Apps Script

{
  "type": "CARD_CLICKED",
  "common": { "formInputs": {
    "contactName": { "": { "stringInputs": {
      "value": ["Kai 0"]
    }}},
    "contactBirthdate": { "": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }}},
      "contactType": { "": { "stringInputs": {
      "value": ["Personal"]
    }}}
  }}
}

為了接收資料，Chat 應用程式會處理 次互動事件，取得使用者在小工具中輸入的值。下表說明如何取得特定表單輸入小工具的值。針對每個小工具，表格會顯示小工具接受的資料類型、互動事件中儲存的值，以及範例值。

表單輸入小工具 輸入資料類型 互動事件的輸入價值 範例值
textInput stringInputs events.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs 如要取得第一個或唯一的值，請使用 events.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker 只接受日期。 dateInput events.common.formInputs.contactBirthdate.dateInput.msSinceEpoch。 1000425600000

將資料轉移到其他卡片

使用者提交資訊卡後，您可能需要傳回其他資訊卡，才能執行下列任一操作：

  • 建立不同部分，協助使用者填寫較長的表單。
  • 讓使用者預覽並確認第一張資訊卡中的資訊，以利他們查看 可以先檢查自己的答案再提交
  • 動態填入表單的其餘部分。比方說 像是即時通訊應用程式 顯示索取預約原因的初始資訊卡。 系統就會根據下列資訊填入另一張資訊卡 預約類型。

如要轉移初始卡片中的資料輸入內容，可以建構 button 包含 actionParameters 的小工具 包含小工具的 name 和使用者輸入內容的值，如下所示 在以下範例中：

{
  "buttonList": {
    "buttons": [{
      "text": "Submit",
      "onClick": {
        "action": {
          "function": "openNextCard",
          "parameters": [{
            "key": "WIDGET_NAME",
            "value": "USER_INPUT_VALUE"
          }]
        }
      }
    }]
  }
}

其中 WIDGET_NAME 是小工具的 name， USER_INPUT_VALUE 是使用者輸入內容。舉例來說 用來收集使用者姓名的輸入內容，小工具名稱為 contactName， 範例值為 Kai O。

使用者按一下按鈕時，Chat 應用程式會收到 CARD_CLICKED 互動事件。如要擷取值，您可以使用 event.common.parameters 物件。

以下範例說明如何將包含使用者輸入資料的參數傳遞至可開啟下一個資訊卡的函式：

Node.js

// Respond to button clicks on cards or dialogs
if (event.type === "CARD_CLICKED") {

  // Open another card.
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    openNextCard(event);
  }
}

Python

  # Respond to button clicks on cards or dialogs
  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_next_card':
        parameters = request.get('common', dict()).get('parameters'),
        return open_next_card(parameters)

Apps Script

// Respond to button clicks on cards or dialogs
function onCardClick(event) {
  if (event.common.invokedFunction === "openNextCard") {
    const parameters = event.common.parameters;
    return openNextCard(parameters);
  }
}

回應提交的表單

接收資訊卡訊息或對話方塊的資料後，Chat 應用程式會回應，確認已收到資料或傳回錯誤。

在以下範例中，Chat 應用程式會傳送 訊息，確認表單已成功收到透過 資訊卡訊息。

Apps Script

function submitCardForm(contactName, contactBirthdate, contactType) {
    return {
      "text": "You entered the following contact information:\n\n" +
      "*Name:* " + contactName + "\n" +
      "*Birthdate:* " + contactBirthdate + "\n" +
      "*Type:* " + contactType
      }
}

如要處理及關閉對話方塊，您必須傳回 ActionResponse 物件，指定是否要傳送確認訊息、更新原始訊息或資訊卡，或是只關閉對話方塊。如需操作步驟，請參閱「關閉對話方塊」。

疑難排解

Google Chat 應用程式或 card 會傳回錯誤， 即時通訊介面顯示「發生錯誤」的訊息。 或「無法處理你的要求」。有時 Chat UI 不會顯示任何錯誤訊息，但 Chat 應用程式或資訊卡會產生意外結果，例如資訊卡訊息可能不會顯示。

雖然 Chat UI 可能不會顯示錯誤訊息，但當您開啟 Chat 應用程式的錯誤記錄功能時，系統會提供說明性錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關說明，請參閱「排解及修正 Google Chat 錯誤」一文。