本頁面由 Cloud Translation API 翻譯而成。

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

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

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

**圖 1**：A 範例符合下列條件的即時通訊應用程式：開啟對話方塊來收集聯絡資訊。

即時通訊應用程式會要求使用者提供資訊，以便在下列情況下執行操作：，包括：

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

必要條件

已啟用互動功能的 Google 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`

將資料轉移到其他卡片

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

建立不同的部分，協助使用者填寫較長的表單。
讓使用者預覽並確認初始資訊卡中的資訊，方便他們在提交前查看答案。
動態填入表單的其他部分。舉例來說，如要提示使用者建立預約，Chat 應用程式可以顯示初始資訊卡，要求使用者提供預約原因，然後填入另一張資訊卡，根據預約類型提供可預約的時間。

如要轉移初始卡片中的資料輸入內容，可以建構 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 這個物件會指定您是否要傳送確認訊息。update 原始訊息或資訊卡，或是直接關閉對話方塊。詳細步驟請參閱關閉對話方塊。

疑難排解

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

雖然 Chat UI 中可能不會顯示錯誤訊息，提供描述性錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關說明，請參閱「排解及修正 Google Chat 錯誤」一文。

查看聯絡人管理工具範例，這是一個 Chat 應用程式，可透過資訊卡訊息和對話方塊提示使用者填寫聯絡表單。
開啟互動式對話方塊

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

必要條件

使用資訊卡建立表單

接收互動式小工具的資料

處理互動事件

HTTP

Apps Script

將資料轉移到其他卡片

Node.js

Python

Apps Script

回應提交的表單

Apps Script

疑難排解

相關主題