本指南將說明如何在 Google Chat API 的 Message 資源上使用 create() 方法，執行下列任一操作：
- 傳送含有文字、資訊卡和互動式小工具的訊息。
- 私下傳送訊息給特定 Chat 使用者。
- 發起或回覆訊息串。
- 為訊息命名，以便在其他 Chat API 要求中指定。
訊息大小 (包括任何文字或資訊卡) 的上限為 32,000 位元組。如要傳送超過此大小的訊息，Chat 應用程式必須改為傳送多則訊息。
除了呼叫 Chat API 建立訊息之外，Chat 應用程式也能建立及傳送訊息以回覆使用者互動，例如在使用者將 Chat 應用程式新增至聊天室後發布歡迎訊息。回應互動時，Chat 應用程式可以使用其他類型的訊息功能，包括互動式對話方塊和連結預覽介面。為了回覆使用者，Chat 應用程式會以同步方式傳回訊息，不會呼叫 Chat API。如要瞭解如何傳送訊息回應互動，請參閱「接收並回覆 Google Chat 應用程式互動內容」。
Chat 如何顯示和屬性使用 Chat API 建立的訊息
您可以使用應用程式驗證和使用者驗證來呼叫 create() 方法。Chat 會根據您使用的驗證類型，決定訊息傳送者的方式。
當您以 Chat 應用程式驗證時，Chat 應用程式就會傳送訊息。
App。當您以使用者身分進行驗證時，Chat 應用程式會代表使用者傳送訊息。Chat 也會顯示 Chat 應用程式名稱，將訊息歸因於 Chat 應用程式。
驗證類型也會決定您可以在訊息中加入哪些訊息功能和介面。透過應用程式驗證，即時通訊應用程式可以傳送含有圖文並列、資訊卡式介面和互動式小工具的訊息。由於 Chat 使用者只能在訊息中傳送文字，因此您只能在使用者驗證功能建立訊息時加入文字。如要進一步瞭解 Chat API 提供的訊息功能，請參閱 Google Chat 訊息總覽。
本指南說明如何使用其中一種驗證類型透過 Chat API 傳送訊息。
必要條件
Node.js
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用並設定 Google Chat API，並為 Chat 應用程式提供名稱、圖示和說明。
- 安裝 Node.js Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中進行驗證的方式，建立存取憑證：
- 如要以 Chat 使用者的身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存為名為
client_secrets.json的 JSON 檔案，並儲存在本機目錄中。 - 如要以 Chat 應用程式進行驗證，請建立服務帳戶憑證，並將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者的身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存為名為
- 根據您想以使用者或 Chat 應用程式身分驗證， 選擇授權範圍。
- Google Chat 聊天室：使用者或發出呼叫的 Chat 應用程式是其中成員。如要以 Chat 應用程式驗證，請將 Chat 應用程式新增至聊天室。
Python
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 使用 Chat 應用程式的名稱、圖示和說明啟用並設定 Google Chat API。
- 安裝 Python Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中驗證的方式建立存取憑證：
- 如要以 Chat 使用者的身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存為名為
client_secrets.json的 JSON 檔案，並儲存在本機目錄中。 - 如要以 Chat 應用程式進行驗證，請建立服務帳戶憑證，並將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者的身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存為名為
- 根據要以使用者或 Chat 應用程式身分進行驗證， 選擇授權範圍。
- Google Chat 聊天室：使用者或發出呼叫的 Chat 應用程式是其中成員。如要以 Chat 應用程式的身分進行驗證，請將 Chat 應用程式新增至聊天室。
Java
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用並設定 Google Chat API，並為 Chat 應用程式提供名稱、圖示和說明。
- 安裝 Java Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中驗證的方式建立存取憑證：
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並以
client_secrets.json檔案格式將憑證儲存至本機目錄。 - 如要以 Chat 應用程式進行驗證，請建立服務帳戶憑證，並將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並以
- 根據要以使用者或 Chat 應用程式身分進行驗證， 選擇授權範圍。
- Google Chat 聊天室：使用者或發出呼叫的 Chat 應用程式是其中成員。如要以 Chat 應用程式驗證，請將 Chat 應用程式新增至聊天室。
Apps Script
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用並設定 Google Chat API，並為 Chat 應用程式提供名稱、圖示和說明。
- 建立獨立的 Apps Script 專案，並啟用進階 Chat 服務。
- 在本指南中，您必須使用使用者或應用程式驗證。如要以 Chat 應用程式驗證，請建立服務帳戶憑證。如需步驟，請參閱「以 Google Chat 應用程式身分驗證及授權」。
- 根據要以使用者或 Chat 應用程式身分進行驗證， 選擇授權範圍。
- Google Chat 聊天室：使用者或發出呼叫的 Chat 應用程式是其中成員。如要以 Chat 應用程式驗證，請將 Chat 應用程式新增至聊天室。
以 Chat 應用程式傳送訊息
本節說明如何使用應用程式驗證功能，傳送包含文字、資訊卡和互動式配件小工具的訊息。
如要使用應用程式驗證功能呼叫 CreateMessage() 方法，您必須在要求中指定下列欄位：
chat.bot授權範圍。- 您要發布訊息的
Space資源。Chat 應用程式必須是聊天室的成員。 - 要建立的
Message資源。如要定義訊息內容，您可以加入圖文並附加一或多個資訊卡介面 (cardsV2)，也可以同時加入這兩者。text
您也可以選擇加入下列項目：
accessoryWidgets欄位，用於加入訊息底部的互動按鈕。- 用於私人傳送訊息的
privateMessageViewer欄位給指定使用者。 messageId欄位：可讓您命名訊息，以便在其他 API 要求中使用。thread.threadKey和messageReplyOption欄位，用於發起或回覆討論串。如果聊天室未使用執行緒，系統會忽略這個欄位。
以下程式碼示範 Chat 應用程式如何傳送訊息，並以 Chat 應用程式形式發布，其中包含文字、卡片和可點選的按鈕：
Node.js
Python
Java
Apps Script
如要執行這個範例，請將 SPACE_NAME 替換為空間 name 欄位的 ID。您可以呼叫 ListSpaces() 方法，或從空間的網址取得 ID。
在郵件底部加入互動式小工具
在本指南的第一個程式碼範例中，Chat 應用程式訊息會在訊息底部顯示可點選的按鈕，稱為配件小工具。配件小工具會顯示在訊息的任何文字或資訊卡之後。您可以使用這些小工具，以多種方式提示使用者與訊息互動，包括：
- 評估訊息的準確度或滿意度。
- 回報與訊息或 Chat 應用程式相關的問題。
- 開啟相關內容的連結，例如說明文件。
- 在特定時間內，從 Chat 應用程式中略過或暫停類似的訊息。
如要新增配件小工具，請在要求主體中加入 accessoryWidgets[] 欄位，並指定要加入的一或多個小工具。
下圖顯示 Chat 應用程式會在文字訊息中附加配件小工具，方便使用者評分 Chat 應用程式的使用體驗。
以下是建立含有兩個附加按鈕的文字訊息要求主體。當使用者按一下按鈕時，對應的函式 (例如 doUpvote) 會處理互動：
{
text: "Rate your experience with this Chat app.",
accessoryWidgets: [{ buttonList: { buttons: [{
icon: { material_icon: {
name: "thumb_up"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doUpvote"
}}
}, {
icon: { material_icon: {
name: "thumb_down"
}},
color: { red: 0, blue: 255, green: 0 },
onClick: { action: {
function: "doDownvote"
}}
}]}}]
}
私下傳送訊息
即時通訊應用程式可私下傳送訊息，讓訊息只供聊天室中的特定使用者查看。當 Chat 應用程式傳送私人訊息時，訊息會顯示標籤，通知使用者該訊息只有他們能看見。
如要使用 Chat API 私下傳送訊息，請在要求主體中指定 privateMessageViewer 欄位。如要指定使用者，請將值設為代表 Chat 使用者的 User 資源。您也可以使用 User 資源的 name 欄位，如以下範例所示：
{
text: "Hello private world!",
privateMessageViewer: {
name: "users/USER_ID"
}
}
如要使用這個範例，請將 USER_ID 替換為使用者的專屬 ID，例如 12345678987654321 或 hao@cymbalgroup.com。如要進一步瞭解如何指定使用者，請參閱「識別及指定 Google Chat 使用者」。
如要傳送私人訊息，必須在要求中省略以下內容：
代表使用者傳送簡訊
本節說明如何使用使用者驗證，代表使用者傳送訊息。在使用者驗證的情況下，訊息內容只能包含文字，且必須省略僅限於 Chat 應用程式可用的訊息功能，包括資訊卡介面和互動式小工具。
如要使用使用者驗證呼叫 CreateMessage() 方法，您必須在要求中指定下列欄位：
- 支援此方法使用者驗證的授權範圍。以下範例使用
chat.messages.create範圍。 - 您要發布訊息的
Space資源。已驗證使用者必須是聊天室的成員。 - 要建立的
Message資源。如要定義訊息內容，您必須加入text欄位。
您也可以選擇加入下列項目：
messageId欄位，可讓您命名訊息，以便在其他 API 要求中使用。- 用於發起或回覆執行緒的
thread.threadKey和messageReplyOption欄位。如果空間未使用執行緒，系統會忽略這個欄位。
以下程式碼示範 Chat 應用程式如何代表已驗證的使用者，在特定聊天室中傳送文字訊息：
Node.js
Python
Java
Apps Script
如要執行這個範例，請將 SPACE_NAME 替換為空間 name 欄位的 ID。您可以呼叫 ListSpaces() 方法，或從空間的網址取得 ID。
在討論串中發起或回覆
如果聊天室使用執行緒，您可以指定新訊息要發起討論串，還是回覆現有討論串。
根據預設，使用 Chat API 建立的訊息會啟動新串流。為了方便您日後識別及回覆該會話串，您可以在要求中指定會話串鍵：
- 在要求主體中指定
thread.threadKey欄位。 - 指定查詢參數
messageReplyOption，以決定鍵已存在時的處理方式。
如要建立回覆現有對話串的訊息，請按照下列步驟操作：
以下程式碼範例說明 Chat 應用程式如何代表已驗證的使用者，傳送文字訊息，以便啟動或回覆以特定聊天室鍵識別的特定會話串：
Node.js
Python
Java
Apps Script
如要執行這個範例，請取代下列項目：
THREAD_KEY：聊天室中的現有執行緒金鑰，如要建立新的執行緒，請使用專屬執行緒名稱。SPACE_NAME：聊天室name欄位的 ID。您可以呼叫ListSpaces()方法，或從空間的網址取得 ID。
為訊息命名
如要在日後的 API 呼叫中擷取或指定訊息，您可以在要求中設定 messageId 欄位，為訊息命名。您可以為訊息命名，藉此指定訊息，而無需儲存系統指派的 ID (由訊息的資源名稱表示，如 name 欄位所示)。
舉例來說，如要使用 get() 方法擷取訊息，您可以使用資源名稱指定要擷取的訊息。資源名稱格式為 spaces/{space}/messages/{message}，其中 {message} 代表系統指派的 ID，或您在建立訊息時設定的自訂名稱。
如要為訊息命名，請在建立訊息時，在 messageId 欄位中指定自訂 ID。messageId 欄位會為 Message 資源的 clientAssignedMessageId 欄位設定值。
您只能在建立訊息時為其命名。您無法為現有訊息命名或修改自訂 ID。自訂 ID 必須符合下列規定：
- 開頭為
client-。例如，client-custom-name是有效的自訂 ID，但custom-name不是。 - 最多包含 63 個字元，且只能使用小寫英文字母、數字和連字號。
- 在單一空間中不得重複。Chat 應用程式無法針對不同訊息使用相同的自訂 ID。
以下程式碼顯示了 Chat 應用程式如何代表已驗證使用者，將包含 ID 的簡訊傳送至特定聊天室：
Node.js
Python
Java
Apps Script
如要執行這個範例，請取代下列項目：
SPACE_NAME：聊天室name欄位的 ID。您可以呼叫ListSpaces()方法，或從空間的網址取得 ID。MESSAGE-ID：開頭為custom-的訊息名稱。不得與 Chat 應用程式在指定空間中建立的任何其他訊息名稱重複。
疑難排解
當 Google Chat 應用程式或資訊卡傳回錯誤時，Chat 介面會顯示「發生錯誤」的訊息。或「無法處理您的要求」。有時 Chat UI 不會顯示任何錯誤訊息，但 Chat 應用程式或資訊卡會產生意外結果，例如資訊卡訊息可能不會顯示。
雖然 Chat UI 可能不會顯示錯誤訊息，但只要開啟 Chat 應用程式的錯誤記錄功能，您就能取得描述性錯誤訊息和記錄資料，協助修正錯誤。如需查看、偵錯及修正錯誤的相關說明，請參閱「排解及修正 Google Chat 錯誤」一文。
相關主題
- 使用資訊卡建立工具設計及預覽 Chat 應用程式的 JSON 資訊卡訊息。
- 設定郵件格式。
- 取得訊息的詳細資料。
- 列出聊天室中的訊息。
- 更新訊息。
- 刪除訊息。
- 在 Google Chat 訊息中識別使用者。
- 使用傳入 Webhook 將訊息傳送至 Google Chat。