設定 Google Chat API

您建立的每個 Google Chat 應用程式，都需要有專屬的 Google Cloud 專案，並啟用及設定 Chat API。

如要透過使用者驗證執行唯讀 API 呼叫 (例如取得聊天室和列出訊息)，只需啟用 API 並建立 OAuth 用戶端。

如要執行建立、更新和刪除 API 呼叫，或部署及測試互動式 Chat 擴充應用程式 (建構為擴充 Chat 的 Google Workspace 外掛程式)，也必須設定 Chat API。您可以在 Chat API 設定中，指定 Chat 擴充應用程式的所有詳細資料，包括顯示名稱、顯示圖片、部署端點和互動功能。

必要條件

• Business 或 Enterprise Google Workspace 帳戶，且可存取 Google Chat。
• 建立 Google Cloud 專案。
• 設定 OAuth 同意畫面。
• 啟用 Google Chat API。

為 Chat 擴充應用程式選擇顯示名稱、顯示圖片和說明

啟用 Chat API 時，您需要設定 Chat 應用程式的詳細資料，這些資料會顯示在 Chat 中，包括顯示名稱、顯示圖片和說明。這些詳細資料只會顯示在 Chat 中。如要將 Chat 擴充應用程式發布至 Marketplace，您也必須指定 Chat 擴充應用程式在 Marketplace 商店資訊中顯示的詳細資料。

設定 Chat 擴充應用程式前，請先準備下列資訊：

欄位	說明	格式
應用程式名稱	Chat 擴充應用程式的顯示名稱。	最多 25 個英數字元
顯示圖片網址	Chat 擴充應用程式的顯示圖片。	指向正方形圖片 (PNG 或 JPEG) 的 HTTPS 網址。 建議大小至少為 256 x 256 像素。
說明	Chat 擴充應用程式用途的簡短說明。	最多 40 個英數字元

Chat 擴充應用程式的名稱、顯示圖片和說明會顯示在 Chat 使用者介面中。對於某些 Chat API 寫入要求，Chat 會使用這項資訊，將 Chat 擴充應用程式在 Chat 中執行的動作歸因於該應用程式。

舉例來說，如果您呼叫 spaces.create() 方法，Chat 會在聊天室建立者的說明中，加入 Chat 擴充應用程式的名稱，如下圖所示：

圖 1. 使用 spaces.create() 方法代表使用者建立聊天室時，Chat 顯示的歸因訊息。

使用者也會透過下列方式查看或使用這項資訊，與 Chat 擴充應用程式互動：

• 使用 @ 號提及 Chat 擴充應用程式，即可將其加入聊天室或傳送訊息。
• 在「應用程式」選單中，找到 Chat 擴充應用程式並發起即時訊息，即時訊息會顯示 Chat 擴充應用程式的名稱和顯示圖片。
• 使用者可以透過撰寫列瀏覽 Chat 擴充應用程式，並查看其名稱、顯示圖片和說明。

在 Google Cloud 控制台中設定 Chat 應用程式

取得 Chat 應用程式詳細資料後，請開啟雲端專案並設定 Chat API：

1. 在 Google Cloud 控制台中，前往 Chat API 頁面，然後按一下「Configuration」(設定) 頁面：

   前往 Chat API 設定頁面

2. 在「Application info」(應用程式資訊) 下方，填寫「App name」(應用程式名稱)、「Avatar URL」(顯示圖片網址) 和「Description」(說明) 欄位。

3. 選用：從「Markup syntax」(標記語法) 選單中，選取 Chat 應用程式訊息的預設標記語法 (「Markdown」或「Chat」)。如要進一步瞭解文字格式，以及 Chat 如何判斷 API 要求的標記語法，請參閱「設定訊息格式」。

4. 在「互動功能」下方，設定 Chat 應用程式是否要回應使用者互動：

   注意： 如果 Chat 擴充應用程式只會呼叫 Chat API，不會接收或回應使用者互動，請將「Enable interactive features」(啟用互動功能) 保持關閉狀態，並跳到下一個步驟。

   如要建構互動式 Chat 應用程式，請開啟「Enable interactive features」(啟用互動功能)，並完成下列步驟：

   1. 在「Functionality」下方：
      • 選用：選取「支援應用程式首頁」，在與 Chat 應用程式的個人即時訊息中，於「首頁」分頁顯示首頁資訊卡。
      • 選取「加入聊天室和群組對話」，即可安裝及使用 Chat 擴充應用程式。根據預設，使用者可以在與 Chat 擴充應用程式的專屬聊天室中，安裝 Chat 擴充應用程式並傳送訊息。使用者也可以在多人聊天室中，新增 Chat 擴充應用程式並與其互動。

   2. 在「Connection settings」(連線設定) 下方，選取要用於接收 Chat 事件物件的架構：

      • 如要使用 HTTP 服務，請選取「HTTP endpoint URL」(HTTP 端點網址)，並提供網址。
      • 如要使用 Google Apps Script 專案，請選取「Apps Script」，並提供專案的部署作業 ID。
      • 如要使用 Dialogflow 代理，請依序選取「Dialogflow」和「Dialogflow CX」或「Dialogflow ES」，然後提供代理的資源名稱。
      • 如要使用 Pub/Sub，請選取「Cloud Pub/Sub」並輸入主題名稱。
      警告： 如果 Apps Script 部署作業 ID 已填入，表示雲端專案已連結至現有的 Google Workspace 外掛程式。如果您在 Chat API 中更新部署作業 ID，外掛程式的部署作業 ID 也會更新，這可能會影響您在 Google Workspace Marketplace 的資訊。如要查看外掛程式設定，請參閱「在 Google Workspace Marketplace SDK 中設定應用程式」。

   3. 選用：如要將事件物件轉送至特定端點或函式，請前往「Connection settings」>「Triggers」，然後提供或更新下列 Chat 觸發條件的回呼端點或函式：

      注意： 如果是 Apps Script，若您不更新觸發條件，則必須實作本節中填入的預設回呼函式 (例如 onMessage、onAddedToSpace、onRemovedFromSpace、onAppCommand 和 onAppHome)。
      • 應用程式首頁 (如果已啟用「支援應用程式首頁」)：使用者在與 Chat 應用程式的個人即時訊息中，開啟「首頁」分頁。
      • 已新增至聊天室：使用者將 Chat 擴充應用程式新增至群組對話或聊天室，或安裝 Chat 擴充應用程式來傳送 1:1 訊息。
      • Message：使用者傳送訊息給 Chat 應用程式。例如，使用者傳送即時訊息給 Chat 應用程式，或在有多位成員的聊天室中 @提及 Chat 應用程式。
      • Removed from space：使用者從聊天室解除安裝或移除 Chat 應用程式。
      • 應用程式指令：使用者從 Chat 應用程式叫用快速指令、斜線指令或訊息動作。

   4. 選用：新增其他互動功能，例如啟動提示詞、指令 (快速指令、斜線指令和訊息動作) 或連結預覽。

   5. 在「Visibility」(顯示設定) 下方指定電子郵件地址，以便在發布至 Google Workspace Marketplace 前，安裝及測試 Chat 擴充應用程式。您最多可以指定五位使用者，或一或多個 Google Workspace 機構中的 Google 群組。

5. 選用：在「Logs」(記錄) 下方，勾選「Log errors to Logging」(將錯誤記錄到 Logging) 核取方塊，即可使用 Google Cloud Logging。詳情請參閱「查詢 Chat 擴充應用程式的錯誤記錄」。

6. 按一下 [儲存]。

儲存設定後，您在 Chat API 的「Visibility」(顯示設定) 中指定的任何人，都可以安裝、測試或使用 Chat 應用程式。如要開始測試及偵錯 Chat 應用程式，請參閱「測試 Google Chat 應用程式的互動功能」。

現有 Google Workspace 外掛程式的注意事項

Chat 擴充應用程式的設定，與擴充其他 Google Workspace 應用程式的 Google Workspace 外掛程式不同。如果外掛程式會擴充其他 Google Workspace 應用程式，請考量下列 Chat 應用程式設定規定：

• 個人和 Google Workspace 管理員都必須能從 Marketplace 安裝您的外掛程式。您可以在 Google Workspace Marketplace SDK 中，調整這些安裝設定。
• Chat 擴充應用程式不會使用您在資訊清單的 addons.common 物件中，為其他 Google Workspace 應用程式設定的名稱和標誌。
• 如果外掛程式已發布至 Google Workspace Marketplace，您無法儲存 Google Chat API 設定變更的草稿。更新並儲存 Chat API 設定後，所有現有使用者都能立即使用更新後的 Chat 擴充應用程式。如要更新 Marketplace 產品資訊，您可以先建立草稿，再提交任何變更。
• 如果您使用 Apps Script 建構外掛程式：
  • 您必須使用與其他外掛程式設定相同的 Apps Script 部署 ID。
  • 您無法使用 Apps Script 編輯器在 Chat 中安裝測試部署項目。請改為直接從 Chat UI 安裝。
• 如果您使用 HTTP 服務建構外掛程式，請在使用 Google Workspace Add-ons API 建立的資訊清單和部署作業中，省略任何 Chat 應用程式設定詳細資料。您在 Google Workspace Marketplace SDK 中指定的 HTTP 部署作業，僅適用於其他 Google Workspace 應用程式。

授予其他使用者設定 Chat API 的權限

您可以授予Chat 應用程式擁有者或 Chat 應用程式檢視者 Google Cloud Identity Access Management (IAM) 角色，將 Chat 應用程式設定頁面的存取權授予特定使用者。具備這些角色的使用者無法透過「APIs & Services」(API 和服務) 資訊主頁前往 Chat 擴充應用程式設定頁面，但可以前往 Chat 擴充應用程式主機雲端專案的 Google Cloud 控制台，存取設定頁面，步驟如下：

https://console.developers.google.com/apis/api/chat.googleapis.com/hangouts-chat?project=PROJECT_ID

其中 PROJECT_ID 是託管 Chat 應用程式的 Google Cloud 專案 ID。

具備專案角色的使用者也可以存取應用程式設定頁面。

如果使用者的自訂角色包含 resourcemanager.projects.(get|update) 權限，則無法存取 Chat 擴充應用程式設定。如要使用自訂角色，請改用 chat.bots.(get|update) 權限。

相關主題

• 選擇 Chat 擴充應用程式架構
• 接收及回應使用者互動
• 測試 Google Chat 應用程式的互動功能

非外掛程式的 Chat 擴充應用程式：設定 Google Chat API

如果您維護的 Chat 擴充應用程式不是 Google Workspace 外掛程式，則設定會使用單一端點處理所有互動事件，而非個別事件觸發條件：

1. 在 Google Cloud 控制台中，前往 Chat API 的「Configuration」(設定) 頁面：

   前往 Chat API 設定頁面

2. 在「互動功能」下方，開啟「啟用互動功能」。

3. 取消勾選「將這個 Chat 擴充應用程式建構為 Google Workspace 外掛程式」。畫面上會顯示對話方塊，請您確認。在對話方塊中，按一下「停用」。

4. 在「功能」下方，視需要選取「支援應用程式首頁」或「加入聊天室和群組對話」。

5. 在「連線設定」下方，為 Chat 擴充應用程式指定單一端點 (「HTTP 端點網址」、「Apps Script」部署作業 ID、「Cloud Pub/Sub 主題名稱」或「Dialogflow」)。

6. 視需要設定「Commands」(指令)、「Link previews」(連結預覽)、「Visibility」(瀏覽權限) 和「Logs」(記錄)，然後按一下「Save」(儲存)。

如要將非外掛程式的 Chat 擴充應用程式，升級為可擴充 Google Chat 的 Google Workspace 外掛程式，請參閱「將 Google Chat 擴充應用程式轉換為 Google Workspace 外掛程式」。