Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

設定 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 擴充應用程式的簡短說明，會在使用者於 Chat 搜尋應用程式時顯示。	最多 40 個英數字元
詳細說明	(選用步驟) Chat 應用程式的功能說明，會在使用者與 Chat 應用程式發起對話，或開啟代理的工作階段首頁時顯示。開發人員預覽版計畫提供。目前僅支援使用 Google Cloud 控制台更新應用程式設定，不支援透過 Google Workspace 外掛程式 API 更新。	最多 250 個字元

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

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

Google Chat 應用程式為使用者建立聊天室。 — **圖 1**. 使用 `spaces.create()` 方法代表使用者建立聊天室時，Chat 顯示的歸屬訊息。

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

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

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

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

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

前往 Chat API 設定頁面
在「Application info」(應用程式資訊) 下方，填寫「App name」(應用程式名稱)、「Avatar URL」(顯示圖片網址) 和「Description」(說明) 欄位。
選用：填寫「Long description」(詳細說明) 欄位 (Google Workspace 開發人員預覽版計畫提供)。
選用：在「Markup syntax」(標記語法) 選單中，選取 Chat 應用程式訊息的預設標記語法 (「Markdown」或「Chat」)。如要進一步瞭解文字格式，以及 Chat 如何判斷 API 要求的標記語法，請參閱「設定訊息格式」。
在「互動功能」下方，設定 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 應用程式的 1 對 1 即時訊息中，開啟「首頁」分頁。
  - 已新增至聊天室：使用者將 Chat 擴充應用程式新增至群組對話或聊天室，或安裝 Chat 擴充應用程式，用於一對一訊息。
  - Message：使用者傳送訊息給 Chat 應用程式。例如，使用者傳送即時訊息給 Chat 應用程式，或在有多位成員的聊天室中 @提及 Chat 應用程式。
  - 從聊天室中移除：使用者從聊天室中解除安裝或移除 Chat 應用程式。
  - 應用程式指令：使用者從 Chat 應用程式叫用快速指令、斜線指令或訊息動作。
4. 選用：新增其他互動功能，例如工作階段、啟動提示詞、指令 (快速指令、斜線指令和訊息動作) 或連結預覽。
5. 在「Visibility」(瀏覽權限) 下方，選取「Make this Chat app available to specific people and groups」(將這個 Chat 應用程式提供給特定使用者和群組)，然後輸入 Google Workspace 機構中個人或 Google 群組的電子郵件地址：
  - 如要自行安裝及測試應用程式，請輸入自己的電子郵件地址。
  - 如要與團隊或整個組織共用內部 Chat 擴充應用程式，而不發布至 Marketplace，請輸入一或多個 Google 群組。群組沒有成員人數限制。如果應用程式要求 chat.app.* 範圍，您仍須發布應用程式，供管理員核准。
  - 如果管理員限制只能安裝許可清單中的 Marketplace 應用程式，Google Cloud 控制台會將這個欄位限制為五個個別使用者電子郵件地址，用於開發。管理員將應用程式加入許可清單後，群組瀏覽權限才會生效。
選用：在「Logs」(記錄) 下方，勾選「Log errors to Logging」(將錯誤記錄到 Logging) 核取方塊，即可使用 Google Cloud Logging。詳情請參閱「查詢 Chat 擴充應用程式的錯誤記錄」。
按一下「儲存」。

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

使用 Google Workspace Add-ons API 設定 Chat 擴充應用程式

您可以使用已註冊 Google Workspace 開發人員預覽版計畫的 Google Cloud 雲端專案，透過程式輔助方式讀取及更新 Google Workspace 外掛程式建構的 Chat 擴充應用程式設定chatAppConfigGoogle Workspace add-ons API，而不必在 Google Cloud 控制台中手動設定 Chat 擴充應用程式。

chatAppConfig 是單例資源，一律存在於每個雲端專案中。首次儲存設定前，資源會包含空白設定 (如果您在首次儲存前讀取資源，GetChatAppConfig 也會傳回空白設定)。由於資源已存在，您不需要另外建立，只要使用 UpdateChatAppConfig 即可儲存初始設定及更新現有設定。

先決條件和驗證

呼叫 GetChatAppConfig 或 UpdateChatAppConfig 之前，請先完成下列必要條件：

將 Google Cloud 雲端專案註冊加入 Google Workspace 開發人員預覽版計畫。
在 Cloud 專案中啟用 Google Workspace 外掛程式 API (gsuiteaddons.googleapis.com)。如要在 Google Cloud 控制台查看或更新 Chat 擴充應用程式設定，或呼叫 Chat API，可以選擇啟用 Google Chat API (chat.googleapis.com)。
以人類使用者身分進行驗證，並使用包含 https://www.googleapis.com/auth/cloud-platform 範圍的 OAuth 2.0 憑證。chatAppConfig 方法不支援服務帳戶驗證。
確認已驗證的使用者具備目標雲端專案的必要 Identity and Access Management (IAM) 權限：
- gsuiteaddons.chatAppConfigs.get 和 chat.bots.get 讀取設定 (GetChatAppConfig)。
- gsuiteaddons.chatAppConfigs.update 和 chat.bots.update，更新設定 (UpdateChatAppConfig)。
如果您使用用戶端程式庫，請以註冊的開發人員預覽版帳戶下載開發人員預覽版用戶端程式庫。

更新 Chat 擴充應用程式設定

如要首次設定 Chat 應用程式或更新現有設定，請將 PATCH 要求 (UpdateChatAppConfig) 傳送至雲端專案的單例 chatAppConfig 資源：

首次儲存 chatAppConfig 為空的雲端專案時，必須提供 displayName (3 到 25 個字元) 和 description (1 到 40 個字元)。如果在初次儲存時省略 interactiveFeatureConfig，Chat 擴充應用程式會設為非互動式。
後續更新時，請使用選用的 updateMask 查詢參數，指定要更新的欄位 (以半形逗號分隔)，或省略 updateMask 以更新所有提供的欄位。更新重複欄位 (appCommands、urlPatterns 或 allowlistedTestingPrincipals) 會取代整個清單。

PATCH https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?updateMask=displayName,description,avatarUri,state,errorLoggingEnabled,markupSyntax,interactiveFeatureConfig
Authorization: Bearer ACCESS_TOKEN
Content-Type: application/json

{
  "name": "projects/PROJECT_NUMBER/chatAppConfig",
  "displayName": "Cymbal Assistant",
  "description": "Helps manage tasks and schedules",
  "avatarUri": "https://www.gstatic.com/dynamite/images/quickstart-app-avatar.png",
  "state": "ACTIVE",
  "errorLoggingEnabled": true,
  "markupSyntax": "MARKUP_SYNTAX_MARKDOWN",
  "interactiveFeatureConfig": {
    "supportsMultiuserSpaces": false,
    "connectionConfig": {
      "httpEndpointConfig": {
        "commonUrl": "https://example.com/chat"
      }
    },
    "appCommands": [
      {
        "commandType": "SLASH_COMMAND",
        "commandId": 1,
        "command": "/help",
        "description": "Show available commands",
        "dialogEnabled": false
      }
    ],
    "urlPatterns": [
      {
        "hostPattern": "example.com",
        "pathPrefix": "tasks/"
      }
    ],
    "allowlistedTestingPrincipals": [
      "USER_EMAIL"
    ]
  }
}

在要求網址、標頭和主體中，替換下列項目：

PROJECT_NUMBER：託管 Chat 擴充應用程式的 Cloud 專案數字編號。
ACCESS_TOKEN：以 https://www.googleapis.com/auth/cloud-platform 範圍授權的使用者 OAuth 2.0 存取權杖。
USER_EMAIL：Google Workspace 組織中的電子郵件地址或 Google 群組，用於加入許可清單，以便測試 Chat 應用程式 (例如您自己的電子郵件地址)。
要求主體中的範例設定欄位 (例如 displayName、description、avatarUri 和 interactiveFeatureConfig，包括端點設定、指令、連結預覽網址模式和測試主體)，以及 Chat 應用程式的值。如要進一步瞭解所有支援的欄位和端點選項，請參閱 projects.chatAppConfig REST 參考資料和 projects.chatAppConfig.patch。

取得 Chat 擴充應用程式設定

如要讀取 Cloud 專案目前的 Chat 擴充應用程式設定，請呼叫 GetChatAppConfig。您可以傳遞選用的 view 查詢參數 (ChatAppConfigView)：

BASIC (預設)：傳回基本中繼資料，不含 interactiveFeatureConfig。
FULL：傳回所有設定欄位，包括 interactiveFeatureConfig。

如果雲端專案尚未儲存 Chat 擴充應用程式設定，這個方法會傳回空白的 ChatAppConfig 物件。

HTTP

GET https://gsuiteaddons.googleapis.com/v1/projects/PROJECT_NUMBER/chatAppConfig?view=FULL
Authorization: Bearer ACCESS_TOKEN

Node.js

const {GSuiteAddOnsClient} = require('@google-cloud/gsuiteaddons').v1;

const client = new GSuiteAddOnsClient();

async function getChatAppConfig() {
  const [response] = await client.getChatAppConfig({
    name: 'projects/PROJECT_NUMBER/chatAppConfig',
    view: 'FULL',
  });
  console.log(JSON.stringify(response, null, 2));
}

getChatAppConfig();

Python

from google.cloud import gsuiteaddons_v1

client = gsuiteaddons_v1.GSuiteAddOnsClient()

request = gsuiteaddons_v1.GetChatAppConfigRequest(
    name="projects/PROJECT_NUMBER/chatAppConfig",
    view=gsuiteaddons_v1.GetChatAppConfigRequest.ChatAppConfigView.FULL,
)
response = client.get_chat_app_config(request=request)
print(response)

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

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

個人和 Google Workspace 管理員都必須能從 Marketplace 安裝您的外掛程式。您可以在 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 建立的 projects.deployments 資訊清單中，省略任何 Chat 應用程式設定詳細資料。您在 Google Workspace Marketplace SDK 中指定的 HTTP 部署項目，僅適用於其他 Google Workspace 應用程式。請改為在 Google Cloud 控制台中設定 Chat 應用程式，或使用 Google Workspace Add-ons API 中的 chatAppConfig 資源。

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

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

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

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

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

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

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

前往 Chat API 設定頁面
在「互動功能」下方，開啟「啟用互動功能」。
取消勾選「將這個 Chat 擴充應用程式建構為 Google Workspace 外掛程式」。畫面上會顯示對話方塊，請您確認。在對話方塊中，按一下「Disable」(停用)。
在「功能」下方，視需要選取「支援應用程式首頁」或「加入聊天室和群組對話」。
在「Connection settings」(連線設定) 下方，為 Chat 應用程式指定單一端點 (「HTTP endpoint URL」(HTTP 端點網址)、「Apps Script」部署作業 ID、「Cloud Pub/Sub topic name」(Cloud Pub/Sub 主題名稱) 或「Dialogflow」)。
視需要設定「指令」、「連結預覽」、「瀏覽權限」和「記錄」，然後按一下「儲存」。

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