本頁面說明如何以 Google Chat 應用程式的形式設定及回應指令。
指令可協助使用者探索及使用 Chat 應用程式的主要功能。只有 Chat 應用程式可以查看指令內容。舉例來說,如果使用者傳送含有斜線指令的訊息,則只有使用者和 Chat 應用程式看得到該訊息。
如要判斷是否應建構指令,以及瞭解如何設計使用者互動,請參閱「定義所有使用者歷程」。
Chat 應用程式指令的類型
建構 Chat 應用程式指令時,可以加上斜線指令或快捷指令。如要探索及使用每種指令,使用者必須執行下列操作:-
斜線指令:使用者只要依序輸入斜線 (
/
) 和預先定義的文字 (例如/about
),即可將指令做為訊息傳送。此外,即時通訊應用程式也可以要求斜線指令文字。舉例來說,斜線指令/search
可能需要輸入要用於搜尋查詢的引數文字。 -
快速指令:使用者只要在 Chat 訊息的回覆區中開啟選單,即可使用指令。如要使用指令,他們按一下「Add」圖示
,然後從選單中選取指令。
-
圖 1. 使用者只要在回覆區域輸入斜線 /
再加上指令名稱,即可探索及使用斜線指令。 -
圖 2.使用者可以在 Chat 訊息的回覆區的選單中探索及使用快速指令。
必要條件
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用 Google Chat API。
- 託管 Chat 應用程式服務架構的 HTTP 端點。
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用 Google Chat API。
- 建立獨立的 Apps Script 專案,然後開啟進階 Chat 服務。
- 新增
addons.chat
物件和任何必要範圍 (oauthScopes
) 或 HTTPS 網址前置字串 (urlFetchWhitelist
),即可在資訊清單中設定 Chat。
設定指令
本節說明如何完成下列步驟以設定指令:
- 為指令建立名稱和說明。
- 在 Google Cloud 控制台中設定指令。
為指令命名並輸入說明
指令的名稱是使用者輸入或選取的內容來叫用 Chat 應用程式。名稱下方也會出現簡短說明,提示使用者如何使用指令:

為指令選擇名稱和說明時,請參考下列建議:
如何為指令命名:
- 使用簡短、描述性且可行的字詞或詞組,讓使用者清楚瞭解指令。舉例來說,請使用
Remind me
,而不要使用Create a reminder
。 - 建議您為指令使用不重複或一般名稱。如果您的指令描述的是一般互動或功能,您可以使用使用者容易辨識且預期的常見名稱,例如
Settings
或Feedback
。否則,請嘗試使用不重複的指令名稱,因為如果其他 Chat 應用程式的指令名稱相同,使用者就必須篩選類似的指令,以尋找並使用您的指令名稱。
如何描述指令:
- 說明應力求簡短明確,讓使用者瞭解指令的使用方式。
- 讓使用者瞭解指令是否有任何格式規定。舉例來說,如果您建立的斜線指令需要引數文字,請將說明設定為類似
Remind me to do [something] at [time]
的內容。 - 讓使用者瞭解 Chat 應用程式是否會回覆聊天室中的所有人,或回覆指令的使用者私下回覆。舉例來說,針對快速指令
About
,您可以將其描述為Learn about this app (Only visible to you)
。
在 Google Cloud 控制台中設定指令
如要建立斜線或快速指令,請在 Google Chat API 的 Chat 應用程式設定中指定該指令的相關資訊。
如要在 Google Chat API 中設定指令,請完成下列步驟:如要在 Google Chat API 中設定斜線指令,請完成下列步驟:
在 Google Cloud 控制台中,點選「選單」圖示 > API 和服務 > 已啟用的 API 和服務 > Google Chat API
按一下「設定」。
在「連線設定」底下,前往「觸發條件」,指定您的端點詳細資料。您必須在下一節中使用這個觸發條件來回應指令。
- HTTP 端點網址:您可以在此指定一個常見的 HTTP 端點網址。或者,如要針對不同的觸發條件使用不同的 HTTP 端點,請直接在「App command」(應用程式指令) 欄位中指定端點。
- Apps Script:輸入 Apps Script 部署作業 ID。根據預設,系統會叫用
onAppCommand
函式。如要使用其他 Apps Script 函式,請在「App command」(應用程式指令) 欄位中指定自訂函式名稱。
按一下「指令」下方的「新增指令」。
輸入下列有關指令的資訊:
- 指令 ID:從 1 到 1000 的數字,Chat 應用程式會使用這個數字來辨識指令並傳回回應。
- 說明:說明指令的使用方式及設定格式的文字。說明的長度上限為 50 個半形字元。
- 指令類型:選取「快速指令」或「斜線指令」。
- 為快速指令或斜線指令指定名稱:
- 快速指令名稱:使用者從選單中選取以叫用指令的顯示名稱。長度上限為 50 個半形字元,並加入特殊字元。例如
Remind me
。 - 「Slash 指令名稱」:使用者在訊息中輸入用於叫用指令的文字。開頭須為斜線、只包含文字,長度上限為 50 個半形字元。例如
/remindMe
。
- 快速指令名稱:使用者從選單中選取以叫用指令的顯示名稱。長度上限為 50 個半形字元,並加入特殊字元。例如
選用:如果想讓 Chat 應用程式使用對話方塊回應指令,請勾選「Open aDialog」核取方塊。
按一下 [儲存]。
這樣就能為 Chat 應用程式設定這個指令。
回應指令
當使用者使用指令時,Chat 應用程式會接收事件物件。事件酬載包含 appCommandPayload
物件,其中包含叫用的指令的詳細資料 (包括指令 ID 和指令類型),方便您傳回適當的回應。事件物件會傳送至您在設定 App 指令觸發條件時指定的 HTTP 端點或 Apps Script 函式。

/help
,說明如何取得支援。以下程式碼示範如何透過文字訊息回覆斜線指令 /about
。為了回應斜線指令,Chat 應用程式會透過應用程式指令觸發條件處理事件物件。如果事件物件的酬載包含斜線指令 ID,Chat 應用程式會傳回包含 createMessageAction
物件的 DataActions
動作:
// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;
/**
* Google Cloud Function that responds to events sent from a
* Google Chat space.
*
* @param {Object} req Request sent from Google Chat space
* @param {Object} res Response to send back
*/
exports.avatarApp = function avatarApp(req, res) {
if (req.method === 'GET' || !req.body.chat) {
return res.send('Hello! This function is meant to be used ' +
'in a Google Chat Space.');
}
// Stores the Google Chat event as a variable.
const chatEvent = req.body.chat;
// Handles events that contain payloads about commands
if (chatEvent.appCommandPayload) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = chatEvent.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}});
}
// Handles MESSAGE events
} else if (chatEvent.messagePayload) {
// Stores the Google Chat event as a variable.
const chatMessage = chatEvent.messagePayload.message;
// Replies with the sender's avatar in a card otherwise.
const displayName = chatMessage.sender.displayName;
const avatarUrl = chatMessage.sender.avatarUrl;
res.send({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Here\'s your avatar',
cardsV2: [{
cardId: 'avatarCard',
card: {
name: 'Avatar Card',
header: {
title: `Hello ${displayName}!`,
},
sections: [{
widgets: [{
textParagraph: { text: 'Your avatar picture: ' }
}, {
image: { imageUrl: avatarUrl }
}]
}]
}
}]
}}}}});
}
};
// The ID of the slash command "/about".
// It's not enabled by default, set to the actual ID to enable it. You must
// use the same ID as set in the Google Chat API configuration.
const ABOUT_COMMAND_ID = 0;
/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
// Stores the Google Chat event as a variable.
const chatMessage = event.chat.messagePayload.message;
// Replies with the sender's avatar in a card otherwise.
const displayName = chatMessage.sender.displayName;
const avatarUrl = chatMessage.sender.avatarUrl;
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'Here\'s your avatar',
cardsV2: [{
cardId: 'avatarCard',
card: {
name: 'Avatar Card',
header: {
title: `Hello ${displayName}!`,
},
sections: [{
widgets: [{
textParagraph: { text: 'Your avatar picture: ' }
}, {
image: { imageUrl: avatarUrl }
}]
}]
}
}]
}}}}};
}
/**
* Responds to an APP_COMMAND event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onAppCommand(event) {
// Stores the Google Chat app command metadata as a variable.
const appCommandMetadata = event.chat.appCommandPayload.appCommandMetadata;
// Executes the slash command logic based on its ID.
// Slash command IDs are set in the Google Chat API configuration.
switch (appCommandMetadata.appCommandId) {
case ABOUT_COMMAND_ID :
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
text: 'The Avatar app replies to Google Chat messages.'
}}}}};
}
}
如要使用這個程式碼範例,請將 ABOUT_COMMAND_ID
替換為您在在 Chat API 中設定指令時指定的指令 ID。
測試指令
如要測試指令和程式碼,請參閱「測試 Google Chat 應用程式的互動功能」。
如要瞭解如何在 Chat UI 中測試及使用指令,請參閱 Google Chat 說明文件中的「在 Google Chat 中使用應用程式」一文。