回覆 Google Chat 應用程式指令

本頁面說明如何以 Google Chat 應用程式的形式設定及回應指令。

指令可協助使用者探索及使用 Chat 應用程式的主要功能。只有 Chat 應用程式可以查看指令內容。舉例來說,如果使用者傳送含有斜線指令的訊息,則只有使用者和 Chat 應用程式看得到該訊息。

如要判斷是否應建構指令,以及瞭解如何設計使用者互動,請參閱「定義所有使用者歷程」。

Chat 應用程式指令的類型

建構 Chat 應用程式指令時,可以加上斜線指令或快捷指令。如要探索及使用每種指令,使用者必須執行下列操作:
  1. 斜線指令:使用者只要依序輸入斜線 (/) 和預先定義的文字 (例如 /about),即可將指令做為訊息傳送。此外,即時通訊應用程式也可以要求斜線指令文字。舉例來說,斜線指令 /search 可能需要輸入要用於搜尋查詢的引數文字。
  2. 快速指令:使用者只要在 Chat 訊息的回覆區中開啟選單,即可使用指令。如要使用指令,他們按一下「Add」圖示 ,然後從選單中選取指令。
下圖顯示使用者如何找到斜線指令選單和快速指令:
  • 使用者發現斜線指令。
    圖 1. 使用者只要在回覆區域輸入斜線 / 再加上指令名稱,即可探索及使用斜線指令。
  • 使用者從選單中查看快速指令。
    圖 2.使用者可以在 Chat 訊息的回覆區的選單中探索及使用快速指令。

必要條件

HTTP Apps Script

設定指令

本節說明如何完成下列步驟以設定指令:

  1. 為指令建立名稱和說明
  2. 在 Google Cloud 控制台中設定指令

為指令命名並輸入說明

指令的名稱是使用者輸入或選取的內容來叫用 Chat 應用程式。名稱下方也會出現簡短說明,提示使用者如何使用指令:

Slash 指令名稱和說明
圖 3:斜線指令的名稱和說明。

為指令選擇名稱和說明時,請參考下列建議:

如何為指令命名:

  • 使用簡短、描述性且可行的字詞或詞組,讓使用者清楚瞭解指令。舉例來說,請使用 Remind me,而不要使用 Create a reminder
  • 建議您為指令使用不重複或一般名稱。如果您的指令描述的是一般互動或功能,您可以使用使用者容易辨識且預期的常見名稱,例如 SettingsFeedback。否則,請嘗試使用不重複的指令名稱,因為如果其他 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 中設定斜線指令,請完成下列步驟:

  1. 在 Google Cloud 控制台中,點選「選單」圖示 > API 和服務 > 已啟用的 API 和服務 > Google Chat API

    前往 Google Chat API 頁面

  2. 按一下「設定」

  3. 在「連線設定」底下,前往「觸發條件」,指定您的端點詳細資料。您必須在下一節中使用這個觸發條件來回應指令。

    1. HTTP 端點網址:您可以在此指定一個常見的 HTTP 端點網址。或者,如要針對不同的觸發條件使用不同的 HTTP 端點,請直接在「App command」(應用程式指令) 欄位中指定端點。
    2. Apps Script:輸入 Apps Script 部署作業 ID。根據預設,系統會叫用 onAppCommand 函式。如要使用其他 Apps Script 函式,請在「App command」(應用程式指令) 欄位中指定自訂函式名稱。
  4. 按一下「指令」下方的「新增指令」

  5. 輸入下列有關指令的資訊:

    1. 指令 ID:從 1 到 1000 的數字,Chat 應用程式會使用這個數字來辨識指令並傳回回應。
    2. 說明:說明指令的使用方式及設定格式的文字。說明的長度上限為 50 個半形字元。
    3. 指令類型:選取「快速指令」或「斜線指令」
    4. 為快速指令或斜線指令指定名稱:
      • 快速指令名稱:使用者從選單中選取以叫用指令的顯示名稱。長度上限為 50 個半形字元,並加入特殊字元。例如 Remind me
      • 「Slash 指令名稱」:使用者在訊息中輸入用於叫用指令的文字。開頭須為斜線、只包含文字,長度上限為 50 個半形字元。例如 /remindMe
  6. 選用:如果想讓 Chat 應用程式使用對話方塊回應指令,請勾選「Open aDialog」核取方塊。

  7. 按一下 [儲存]

這樣就能為 Chat 應用程式設定這個指令。

回應指令

當使用者使用指令時,Chat 應用程式會接收事件物件。事件酬載包含 appCommandPayload 物件,其中包含叫用的指令的詳細資料 (包括指令 ID 和指令類型),方便您傳回適當的回應。事件物件會傳送至您在設定 App 指令觸發條件時指定的 HTTP 端點或 Apps Script 函式。

Cymbal Labs Chat 應用程式的私人訊息。這則訊息顯示 Chat 應用程式是由 Cymbal Labs 所建立,並分享說明文件連結,以及與支援團隊聯絡的連結。
Chat 應用程式會以私密方式回應斜線指令 /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 中使用應用程式」一文。