以 Google Chat 應用程式的形式回應斜線指令

本頁說明如何設定及回應 Google Chat 應用程式。

斜線指令是使用者叫用這類指令並與其互動的常見方式 Chat 應用程式。斜線指令還能幫助使用者 使用 Chat 應用程式的重要功能

如要使用斜線指令,使用者只要輸入斜線 (/),然後輸入簡短文字指令: (例如 /about) 即可取得 Chat 應用程式的資訊。 使用者只要在網址列輸入斜線 Google Chat 畫面會列出視窗,當中列出 Chat 擴充應用程式:

斜線指令視窗
圖 1:使用者在 Google Chat 中輸入斜線後顯示的視窗。

如要判斷是否應設定斜線指令,以及瞭解 設計使用者互動,請參閱 定義所有使用者歷程

包含私人回應的斜線指令

當使用者傳送的訊息含有斜線指令時, 不會向使用者顯示如果 您已設定將 Chat 應用程式新增至聊天室 多人共用時,建議您回應斜線指令 以私密方式,保護使用者與 Chat 應用程式。

舉例來說,假設您要瞭解的是 使用者可使用 /about/help 等指令,探索聊天室。 為避免通知聊天室中的其他成員, 即時通訊應用程式可以使用以下資訊進行私密回覆: 瞭解如何使用 Chat 應用程式並取得支援服務。

必要條件

Node.js

已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程

Apps Script

已啟用互動功能的 Google Chat 應用程式。如要建立 ,請完成快速入門導覽課程

Python

已啟用互動功能的 Google Chat 應用程式。如要建立 請使用 HTTP 服務互動式即時通訊應用程式,請完成快速入門導覽課程

設定斜線指令

本節說明如何完成以下設定斜線 指令:

  1. 為斜線指令建立名稱
  2. 在 Google Chat API 中設定斜線指令

為斜線指令命名

斜線指令的名稱是使用者在 Chat 訊息中輸入的名稱 即可叫用 Chat 應用程式亦提供簡短說明 ,藉此提示使用者進一步瞭解如何使用指令:

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

為斜線指令選擇名稱和說明時,請考慮使用 以下建議:

  • 如何為斜線指令命名:

    • 使用簡短、敘述性且能採取行動的字詞或詞組,做為 使用簡單明瞭的指令舉例來說 /createAReminder,使用 /remindMe
    • 如果您的指令包含多個字詞,請協助使用者閱讀指令。 第一個字是全部小寫,然後再將第一個字的大寫 其他字詞的字母。例如,我不是 /updatecontact 使用 /updateContact
    • 請思考要對指令使用不重複名稱或一般名稱。如果 您的指令說明瞭一般互動或功能,您可以使用 使用者熟悉且預期的通用名稱,例如 /settings/feedback。否則,請嘗試使用不重複的指令名稱,因為如果您的 其他 Chat 應用程式的指令名稱相同,使用者必須 篩選類似的指令,以尋找和使用您的
  • 如何描述斜線指令:

    • 說明以簡潔扼要的方式提供使用者預期 他們叫用這個指令時
    • 讓使用者瞭解指令是否有任何格式規定。 舉例來說,假設您建立需要引數的 /remindMe 指令 請將說明設為 Remind me to do [something] at [time] 之類的名稱。
    • 告知使用者 Chat 應用程式是否會回覆 聊天室中的所有成員,或僅限叫用指令的使用者查看。 舉例來說,對於斜線指令 /about,您可以將其描述為 Learn about this app (Only visible to you)。如要私下回覆 斜線指令,請參閱「使用私人訊息回應」一節。

在 Google Chat API 中設定斜線指令

如要建立斜線指令,您必須在 Chat API 的 Chat 應用程式設定。

如要在 Google Chat API 中設定斜線指令,請完成下列步驟 步驟:

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

    前往 Google Chat API 頁面

  2. 按一下「設定」

  3. 在「斜線指令」下方,按一下「新增斜線指令」

  4. 輸入指令的名稱、指令 ID 和說明:

    1. 「Name」:指令的顯示名稱,以及使用者輸入的內容 即可叫用應用程式開頭須為斜線、只包含文字,且 最多 50 個半形字元
    2. 說明:說明使用方法和格式的文字 非必填的旗標說明的長度上限為 50 個半形字元。
    3. 指令 ID:介於 1 到 1000 的 用來辨識斜線指令的 Chat 應用程式 並傳回回應
  5. 選用:如果想讓 Chat 應用程式回覆 找出內含 dialog 的指令,然後選取 「開啟對話方塊」核取方塊。

  6. 按一下 [儲存]

系統隨即會為 Chat 應用程式設定斜線指令。

回應斜線指令

當使用者建立含有斜線指令的 Chat 訊息時, 您的 Chat 應用程式收到 MESSAGE 互動事件。 事件酬載包含 slashCommandslashCommandMetadata 如需儲存大量結構化物件 建議使用 Cloud Bigtable這些物件含有訊息中所用指令的詳細資料 ,以便傳回適當的回應。

私人訊息:
  Cymbal Labs 即時通訊應用程式。這則訊息會顯示
  Chat 擴充應用程式是由 Cymbal Labs 所製作,並分享連結
  說明文件,以及與支援團隊聯絡的連結。
Chat 擴充應用程式會以私密方式回覆 斜線指令 /help 說明如何取得支援。

以下程式碼為 Chat 應用程式範例 回應 /help 斜線指令 並偵測 MESSAGE 個互動事件 訊息是否包含相符的指令 ID。如果郵件包含 指令 ID,則 Chat 應用程式會傳回私人訊息 說明如何取得協助:

Node.js

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {!Object} req Request sent from Google Chat app
* @param {!Object} res Response to send back
*
* @return {!Object} respond to slash command
*/
exports.onMessage = function onMessage(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    return res.send('Hello! This function is meant to be used in Google Chat app.');
  }

  const event = req.body;

  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/help", responds with a private text message.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 'ID': // The ID for your slash command
        return res.json({
          privateMessageViewer: event.user, // Optional. Responds privately to the slash command.
          text: 'This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>.'
        });
    }
  }

  // If the Chat app doesn't detect a slash command, it responds
  // with a private text message
  return res.json({
    privateMessageViewer: event.user,
    text: 'Try a slash command.'
  });
};

Apps Script

/**
* Responds to a MESSAGE event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case ID: // The ID for your slash command
        return {
          "privateMessageViewer": event.user, // Optional. Responds privately to the slash command.
          "text": "This Chat app was created by Cymbal Labs. To get help with this app, <https://cymbalgroup.com/docs|see our documentation> or <https://cymbalgroup.com/support|contact our support team>."
        };
    }
  }
  else {
    return { "text": "Try a slash command.", "privateMessageViewer": event.user };
  }
}

Python

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  if req.method == 'GET':
    return 'Hello! This function must be called from Google Chat.'

  request = req.get_json(silent=True)

  # Checks for the presence of event.message.slashCommand.
  # If the slash command is "/help", responds with a private text message.
  if request.get('message', {}).get('slashCommand'):
    command_id = request.get('message', {}).get('slashCommand').get('commandId')
    if command_id == 'ID': # The ID for your slash command
      return {
          'privateMessageViewer': request.get('user'),
          'text': (
              'This Chat app was created by Cymbal Labs. To get help with this'
              ' app, <https://cymbalgroup.com/docs|see our documentation> or'
              ' <https://cymbalgroup.com/support|contact our support team>.'
          ),
      }

  return {
      'privateMessageViewer': request.get('user'), # Optional. Responds privately to the slash command.
      'text': 'Try a slash command.',
  }

ID 替換成您所需的指令 ID 可用於 在 Chat API 中設定斜線指令。 如要測試此程式碼,請參閱 測試 Google Chat 應用程式的互動功能