本指南說明如何使用 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 應用程式可以傳送含有 RTF 文字、介面卡和互動式小工具的訊息。由於 Chat 使用者只能在訊息中傳送文字，因此使用使用者驗證建立訊息時，只能加入文字。如要進一步瞭解 Chat API 提供的訊息功能，請參閱「Google Chat 訊息總覽」。
本指南說明如何使用任一驗證類型，透過 Chat API 傳送訊息。
必要條件
Node.js
- 具有 Google Chat 存取權的 Business 或 Enterprise 版 Google Workspace 帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用及設定 Google Chat API，並為 Chat 應用程式命名、設定圖示和說明。
- 安裝 Node.js Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中驗證的方式，建立存取憑證：
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
credentials.json的 JSON 檔案。 - 如要以 Chat 應用程式的身分進行驗證，請建立服務帳戶憑證，然後將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
- 根據您要以使用者或 Chat 應用程式的身分驗證，選擇授權範圍。
- 經過驗證的使用者或呼叫的 Chat 應用程式所屬的 Google Chat 聊天室。如要以 Chat 應用程式的身分驗證，請將 Chat 應用程式新增至聊天室。
Python
- 具有 Google Chat 存取權的 Business 或 Enterprise 版 Google Workspace 帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用及設定 Google Chat API，並為 Chat 應用程式命名、設定圖示和說明。
- 安裝 Python Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中驗證的方式，建立存取憑證：
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
credentials.json的 JSON 檔案。 - 如要以 Chat 應用程式的身分進行驗證，請建立服務帳戶憑證，然後將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
- 根據您要以使用者或 Chat 應用程式的身分驗證，選擇授權範圍。
- 經過驗證的使用者或呼叫的 Chat 應用程式所屬的 Google Chat 聊天室。如要以 Chat 應用程式的身分驗證，請將 Chat 應用程式新增至聊天室。
Java
- 具有 Google Chat 存取權的 Business 或 Enterprise 版 Google Workspace 帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用及設定 Google Chat API，並為 Chat 應用程式命名、設定圖示和說明。
- 安裝 Java Cloud 用戶端程式庫。
- 根據您要在 Google Chat API 要求中驗證的方式，建立存取憑證：
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
credentials.json的 JSON 檔案。 - 如要以 Chat 應用程式的身分進行驗證，請建立服務帳戶憑證，然後將憑證儲存為名為
credentials.json的 JSON 檔案。
- 如要以 Chat 使用者身分進行驗證，請建立 OAuth 用戶端 ID 憑證，並將憑證儲存至本機目錄，命名為
- 根據您要以使用者或 Chat 應用程式的身分驗證，選擇授權範圍。
- 經過驗證的使用者或呼叫的 Chat 應用程式所屬的 Google Chat 聊天室。如要以 Chat 應用程式的身分驗證，請將 Chat 應用程式新增至聊天室。
Apps Script
- 具有 Google Chat 存取權的 Business 或 Enterprise 版 Google Workspace 帳戶。
- 設定環境：
- 建立 Google Cloud 專案。
- 設定 OAuth 同意畫面。
- 啟用及設定 Google Chat API，並為 Chat 應用程式命名、設定圖示和說明。
- 建立獨立的 Apps Script 專案，並開啟進階 Chat 服務。
- 在本指南中，您必須使用使用者或應用程式驗證。如要以 Chat 應用程式的身分進行驗證，請建立服務帳戶憑證。如需相關步驟，請參閱「以 Google Chat 擴充應用程式的身分驗證及授權」。
- 根據您要以使用者或 Chat 應用程式的身分驗證，選擇授權範圍。
- 經過驗證的使用者或呼叫的 Chat 應用程式所屬的 Google Chat 聊天室。如要以 Chat 應用程式的身分驗證，請將 Chat 應用程式新增至聊天室。
以 Chat 應用程式身分傳送訊息
本節說明如何使用應用程式驗證，傳送含有文字、資訊卡和互動式配件小工具的訊息。
如要使用應用程式驗證呼叫 CreateMessage() 方法，您必須在要求中指定下列欄位：
chat.bot授權範圍。- 要在其中發布訊息的
Space資源。Chat 應用程式必須是該空間的成員。 - 要建立的
Message資源。如要定義訊息內容，可以加入 RTF 文字 (text)、 一或多個資訊卡介面 (cardsV2)， 或兩者皆可。
視需要加入下列項目：
accessoryWidgets欄位，可在訊息底部加入互動式按鈕。privateMessageViewer欄位，可私下傳送訊息給特定使用者。messageId欄位，可讓您為訊息命名，以便在其他 API 要求中使用。thread.threadKey和messageReplyOption欄位，可發起或回覆討論串。如果空間未使用執行緒，系統會忽略這個欄位。
以下程式碼範例說明 Chat 應用程式如何傳送以 Chat 應用程式身分發布的訊息，其中包含文字、資訊卡，以及訊息底部的可點選按鈕：
Node.js
Python
Java
Apps Script
如要執行這個範例，請將 SPACE_NAME 替換為空間的 name 欄位中的 ID。您可以呼叫 ListSpaces() 方法，或從空間的網址取得 ID。
在郵件底部新增互動式小工具
在本指南的第一個程式碼範例中，即時通訊應用程式訊息會在訊息底部顯示可點選的按鈕，也就是所謂的配件小工具。配件小工具會顯示在郵件中的任何文字或資訊卡後方。您可以透過這些小工具，提示使用者以多種方式與訊息互動，包括：
- 評估訊息的準確度或滿意度。
- 回報訊息或 Google Chat 應用程式的問題。
- 開啟相關內容的連結，例如文件。
- 在特定時間內，從 Google 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 應用程式傳送私人訊息時，訊息會顯示標籤，通知使用者只有他們能查看這則訊息。
如要使用 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 使用者介面未顯示錯誤訊息，只要開啟 Chat 應用程式的錯誤記錄功能，系統就會提供說明性錯誤訊息和記錄資料，協助您修正錯誤。如需查看、偵錯及修正錯誤的相關協助，請參閱「排解及修正 Google Chat 錯誤」。
相關主題
- 使用 Card Builder 設計及預覽 Chat 應用程式的 JSON 訊息。
- 設定訊息格式。
- 取得訊息詳細資料。
- 列出聊天室中的訊息。
- 更新訊息。
- 刪除訊息。
- 在 Google Chat 訊息中識別使用者。
- 使用傳入 Webhook 將訊息傳送至 Google Chat。