本頁面說明 Google Chat 應用程式如何開啟對話方塊,顯示使用者介面 (UI) 並回應使用者。
對話方塊是基於資訊卡的視窗介面,可從 Chat 聊天室或訊息開啟。對話方塊及其內容只會顯示給開啟對話方塊的使用者。
Chat 擴充應用程式可以使用對話方塊,向 Chat 使用者要求及收集資訊,包括多步驟表單。如要進一步瞭解如何建構表單輸入內容,請參閱「收集及處理使用者資訊」。
必要條件
HTTP
可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構一個,請完成 HTTP 快速入門導覽。
Apps Script
可擴充 Google Chat 功能的 Google Workspace 外掛程式。如要建構巨集,請完成 Apps Script 快速入門。
開啟對話方塊


本節說明如何透過下列方式回應及設定對話:
- 透過使用者互動觸發對話方塊要求。
- 傳回並開啟對話方塊,處理要求。
- 使用者提交資訊後,請關閉對話方塊或傳回另一個對話方塊,以處理提交內容。
觸發對話方塊要求
Chat 應用程式只能在回應使用者互動時開啟對話方塊,例如指令或資訊卡中訊息的按鈕點選動作。
如要透過對話方塊回覆使用者,Chat 應用程式必須建構會觸發對話方塊要求的互動,例如:
- 回應指令。如要透過指令觸發要求,請在設定指令時勾選「開啟對話方塊」核取方塊。
- 回應按鈕點擊動作:在訊息中,無論是資訊卡的一部分或位於訊息底部,如要從訊息中的按鈕觸發要求,請將按鈕的
onClick
動作設定為interaction
,並將其OPEN_DIALOG
設為OPEN_DIALOG
。

/addContact
斜線指令。訊息中也會包含按鈕,使用者點選即可觸發指令。
下列 JSON 顯示如何從訊息中的按鈕觸發對話方塊要求。如要開啟對話方塊,請將按鈕的欄位設為 OPEN_DIALOG
:
onClick.action.interaction
{
"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
。如要瞭解如何收集及處理對話方塊中的資訊,請參閱「收集及處理 Google Chat 使用者的資訊」。
您的 Chat 應用程式必須回應事件物件,方法如下:
選用:傳回其他對話方塊
使用者提交初始對話方塊後,Chat 應用程式可以傳回一或多個額外對話方塊,協助使用者在提交前檢查資訊、填寫多步驟表單,或動態填入表單內容。
如要處理使用者輸入的資料,Chat 應用程式會在事件的 commonEventObject.formInputs
物件中處理資料。如要進一步瞭解如何從輸入小工具擷取值,請參閱「收集及處理使用者資訊」。
如要追蹤使用者在初始對話方塊中輸入的任何資料,您必須在開啟下一個對話方塊的按鈕中新增參數。詳情請參閱「將資料轉移至其他卡片」。
在這個範例中,Google 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
這個範例會傳回 card 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
。
選用:顯示暫時性通知
關閉對話方塊時,您也可以向與應用程式互動的使用者顯示臨時文字通知。
如要顯示通知,請傳回 RenderActions
物件,並設定 notification
欄位。
以下範例會檢查參數是否有效,並視結果關閉對話方塊,同時顯示文字通知:
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
物件,其中包含下列其中一項動作:
UpdateMessageAction
: 更新 Chat 應用程式傳送的訊息,例如使用者要求對話的訊息。UpdateInlinePreviewAction
: 從連結預覽更新資訊卡。
疑難排解
如果 Google Chat 應用程式或資訊卡傳回錯誤,Chat 介面會顯示「發生錯誤」訊息。或「無法處理您的要求」。有時 Chat UI 不會顯示任何錯誤訊息,但 Chat 應用程式或資訊卡會產生非預期結果,例如資訊卡訊息可能不會顯示。
即使 Chat 使用者介面未顯示錯誤訊息,只要開啟 Chat 應用程式的錯誤記錄功能,系統就會提供說明性錯誤訊息和記錄資料,協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助,請參閱「排解及修正 Google Chat 錯誤」。