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

本指南說明 Google Chat 應用程式如何在以卡片為基礎的介面中建立表單輸入內容，以便收集及處理使用者提供的資訊。

在 Google Chat 中，使用者會看到附加元件，就像 Google Chat 應用程式一樣。詳情請參閱「擴充 Google Chat 總覽」。

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

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

必要條件

使用資訊卡建立表單

如要收集資訊，Chat 應用程式會設計表單及其輸入內容，並將這些項目建構為資訊卡。如要向使用者顯示資訊卡，Chat 應用程式可以使用下列 Chat 介面：

• 含有一或多張資訊卡的即時通訊訊息。
• 對話方塊：在訊息和首頁中開啟新視窗的資訊卡。

Chat 應用程式可以使用下列小工具建立資訊卡：

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

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

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

在以下範例中，資訊卡會使用文字輸入、日期/時間挑選器和選項輸入功能收集聯絡資訊：

如要查看更多可用於收集資訊的互動式小工具範例，請參閱 Google Chat API 說明文件中的「設計互動式資訊卡或對話方塊」。

接收互動式小工具的資料

只要使用者按下按鈕，系統就會觸發 Chat 應用程式的動作，並傳送互動資訊。在事件酬載的 commonEventObject 中，formInputs 物件包含使用者輸入的任何值。

您可以從物件 commonEventObject.formInputs.WIDGET_NAME 擷取值，其中 WIDGET_NAME 是您為小工具指定的 name 欄位。系統會將值傳回為小工具的特定資料類型。

以下顯示事件物件的一部分，其中使用者輸入了每個小工具的值：

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

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

將資料轉移到其他卡片

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

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

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

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

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

使用者按下按鈕時，Chat 應用程式會收到事件物件，您可以透過該物件接收資料。

回應表單提交作業

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

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

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

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

疑難排解

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

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