開啟互動式對話方塊

本頁面說明 Google Chat 應用程式如何開啟對話方塊，以便顯示使用者介面 (UI) 並回應使用者。

在 Google Chat 中，使用者會看到附加元件以 Google Chat 應用程式的形式顯示。詳情請參閱「擴充 Google Chat 總覽」。

對話框是從 Chat 聊天室或訊息開啟的窗格式卡片介面。只有開啟對話方塊的使用者才能查看對話方塊及其內容。

Chat 應用程式可以使用對話方塊，向 Chat 使用者要求及收集資訊，包括多步驟表單。如要進一步瞭解如何建構表單輸入內容，請參閱「收集並處理使用者提供的資訊」。

必要條件

Node.js

可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構一個，請完成HTTP 快速入門。

Apps Script

可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構一個應用程式，請完成 Apps Script 快速入門。

開啟對話方塊

對話方塊內含各種不同的小工具。
圖 1：即時通訊應用程式開啟對話方塊來收集聯絡人資訊。

本節說明如何回應及設定對話方塊，方法如下：

  1. 透過使用者互動觸發對話方塊要求。
  2. 透過傳回並開啟對話方塊來處理要求。
  3. 使用者提交資訊後，請關閉對話方塊或傳回另一個對話方塊，以便處理提交內容。

觸發對話方塊要求

Chat 應用程式只能開啟對話方塊，以回應使用者互動，例如斜線指令或資訊卡中訊息的按鈕點選動作。

如要透過對話方塊回覆使用者，Chat 應用程式必須建立可觸發對話方塊要求的互動，例如：

  • 回應斜線指令。如要透過斜線指令觸發要求，請在設定指令時勾選「Opens a dialog」核取方塊。
  • 在訊息中回應按鈕點擊動作，可做為資訊卡的一部分，或位於訊息底部。如要透過訊息中的按鈕觸發要求，請將按鈕的 interaction 設為 OPEN_DIALOG，藉此設定按鈕的 onClick 動作。
觸發對話方塊的按鈕
圖 2：Chat 應用程式傳送訊息，提示使用者使用 /addContact 斜線指令。
訊息中也會包含按鈕，使用者可以點選該按鈕觸發指令。

以下 JSON 說明如何透過資訊卡訊息中的按鈕觸發對話方塊要求。如要開啟對話方塊，請將按鈕的 onClick.action.interaction 欄位設為 OPEN_DIALOG：

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

其中 BUTTON_TEXT 是按鈕中顯示的文字，而 ACTION_FUNCTION 是執行開啟初始對話方塊的函式。

開啟初始對話方塊

當使用者觸發對話方塊要求時，Chat 應用程式會收到含有酬載的事件物件，該酬載會指定 dialogEventType 物件為 REQUEST_DIALOG。

如要開啟對話方塊，Chat 應用程式可以透過傳回含有導覽 pushCard 的 RenderActions 物件，回應要求並顯示資訊卡。資訊卡應包含任何使用者介面 (UI) 元素，包括一或多個小工具的 sections[]。如要向使用者收集資訊，您可以指定表單輸入小工具和按鈕小工具。如要進一步瞭解如何設計表單輸入內容，請參閱「收集並處理使用者提供的資訊」。

以下 JSON 顯示 Chat 應用程式如何傳回可開啟對話方塊的回應：

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

其中 BUTTON_TEXT 是按鈕中顯示的文字 (例如 Next 或 Submit)、WIDGETS 代表一或多個表單輸入小工具，而 ACTION_FUNCTION 則是使用者按下按鈕時執行的動作回呼函式。

處理對話方塊提交作業

當使用者按一下提交對話方塊的按鈕時，Chat 應用程式會收到含有 ButtonClickedPayload 物件的事件物件。在酬載中，dialogEventType 設為 SUBMIT_DIALOG。

Chat 應用程式必須透過下列任一操作處理事件物件：

選用：傳回其他對話方塊

使用者提交初始對話方塊後，聊天應用程式可以傳回一或多個額外對話方塊，協助使用者在提交前查看資訊、完成多步驟表單，或動態填入表單內容。

為了處理使用者輸入的資料，Chat 應用程式會處理事件的 commonEventObject.formInputs 物件中的資料。如要進一步瞭解如何從輸入小工具擷取值，請參閱「收集使用者資訊並加以處理」。

如要追蹤使用者在初始對話方塊中輸入的任何資料，您必須在開啟下一個對話方塊的按鈕中加入參數。詳情請參閱「將資料轉移至其他卡片」。

在這個範例中，Chat 應用程式會開啟初始對話方塊，並在提交前顯示第二個確認對話方塊：

Node.js

/**
 * 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;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

這個範例會傳回 卡片 JSON，藉此傳送資訊卡訊息。您也可以使用 Apps Script 卡片服務。

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

其中 WIDGETS 代表任何其他表單輸入小工具。

關閉對話方塊

當使用者按下對話方塊中的提交按鈕時，Chat 應用程式會執行相關聯的動作，並提供事件物件，其中 buttonClickedPayload 設為下列值：

  • isDialogEvent為 true。
  • dialogEventType為 SUBMIT_DIALOG。

Chat 應用程式應傳回 RenderActions 物件，其中 EndNavigation 設為 CLOSE_DIALOG。

選用：顯示通知

關閉對話方塊時，您也可以顯示文字通知。

如要顯示通知，請傳回設定了 notification 欄位的 RenderActions 物件。

以下範例會檢查參數是否有效，並根據結果關閉對話方塊，並顯示文字通知：

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

如要進一步瞭解如何在對話方塊之間傳遞參數，請參閱「將資料轉移至其他資訊卡」。

選用：傳送確認訊息

關閉對話方塊後，您也可以傳送新訊息或更新現有訊息。

如要傳送新訊息，請傳回 DataActions 物件，其中包含使用新訊息設定的 CreateMessageAction 欄位。舉例來說，如要關閉對話方塊並傳送簡訊，請傳回以下內容：

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

如要在使用者提交對話方塊後更新訊息，請傳回包含下列任一動作的 DataActions 物件：

疑難排解

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

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