本頁面說明如何以 Google Chat 應用程式的身分設定及回應指令。
指令可協助使用者探索並使用 Chat 應用程式的重點功能。只有 Chat 應用程式可以查看指令的內容。舉例來說，如果使用者傳送含有斜線指令的訊息，該訊息只會顯示給使用者和 Chat 應用程式。
如要決定是否應建構指令，以及瞭解如何設計使用者互動，請參閱「定義所有使用者歷程」。
Chat 應用程式指令的類型
您可以將 Chat 應用程式指令建構為斜線指令或快速指令。如要探索及使用各類型指令，使用者可以採取下列做法：-
斜線指令：使用者輸入斜線 (
/) 和預先定義的文字 (例如/about)，即可傳送指令訊息。即時通訊應用程式也可以要求斜線指令的引數文字。舉例來說，斜線指令/search可能會要求用於搜尋查詢的引數文字。 -
快速指令：使用者只要在 Chat 訊息的回覆區域開啟選單，即可使用指令。如要使用指令，他們只要按一下「新增」圖示
，然後從選單中選取指令即可。
-
圖 1. 使用者只要在回覆區域中輸入斜線 /後接指令名稱，即可探索及使用斜線指令。 -
圖 2. 使用者可在 Chat 訊息的回覆區域中，透過選單探索及使用快速指令。
必要條件
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用下列 Google Workspace API：
- Google Chat API
- Google Workspace add-ons API
- 可代管 Chat 應用程式服務架構的 HTTP 端點。
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用 Google Chat API。
- 建立獨立的 Apps Script 專案，並啟用進階 Chat 服務。
- 在清單檔中設定 Chat，方法是新增
addons.chat物件和任何必要的範圍 (oauthScopes) 或 HTTPS 網址前置字串 (urlFetchWhitelist)。
設定指令
本節說明如何完成下列步驟來設定指令：
- 為指令建立名稱和說明。
- 在 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 控制台中設定指令
如要建立斜線或快速指令，請在 Chat 應用程式的 Google Chat API 設定中指定指令相關資訊。
如要設定 Google Chat API 中的指令，請完成下列步驟： o 如要在 Google Chat API 中設定斜線指令，請完成下列步驟：
在 Google Cloud 控制台中，依序點選「Menu」圖示 >「API 和服務」 >「已啟用的 API 和服務」 >「Google Chat API」
按一下「設定」。
在「進階設定」下方，前往「觸發條件」，確認「應用程式指令」欄位包含觸發條件，例如 HTTP 端點或 Apps Script 函式。您必須在下一個章節中使用這個觸發事件，才能回應指令。
在「指令」下方，按一下「新增指令」。
輸入指令的下列資訊：
- 指令 ID：Chat 應用程式用來辨識指令並傳回回應的 1 到 1000 之間的數字。
- 指令類型：選取「快速指令」或「斜線指令」。
- 如果要設定斜線指令，請在「斜線指令名稱」欄位中輸入值，指定使用者要輸入哪些內容才能叫用指令。開頭須為斜線，且只能包含文字，長度上限為 50 個半形字元。例如
/remindMe。 - 名稱：指令的易記名稱。名稱長度上限為 50 個半形字元，且可包含特殊字元。
- 說明：說明如何使用及設定指令格式的文字。說明長度上限為 50 個半形字元。
選用：如要讓 Chat 應用程式透過對話方塊回應指令，請選取「Open a dialog」核取方塊。
按一下 [儲存]。
指令現在已為 Chat 應用程式設定。
回應指令
使用者使用指令時，Chat 應用程式會收到事件物件。事件酬載包含 appCommandPayload 物件，其中包含所叫用的指令詳細資料 (包括指令 ID 和指令類型)，以便您傳回適當的回應。事件物件會傳送至您設定 App 指令觸發事件時指定的 HTTP 端點或 Apps Script 函式。
/help，說明如何取得支援。以下程式碼示範 Chat 應用程式如何使用文字訊息回覆斜線指令 /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 中使用應用程式」。