本頁說明如何設定 webhook,以便使用外部觸發條件,將非同步訊息傳送至 Chat 聊天室。例如,您可以設定監控應用程式,以便在伺服器故障時,通知即時通訊人員。如要透過 Chat 應用程式傳送同步訊息,請參閱「傳送訊息」一文。
使用這種架構設計時,使用者無法與 Webhook 或連線的外部應用程式互動,因為通訊是單向的。Webhook 並非對話式服務。無法回覆或接收來自使用者的訊息或 Chat 應用程式互動事件。如要回應訊息,請建構 Chat 應用程式,而非 Webhook。
雖然 webhook 在技術上並非 Chat 應用程式 (因為 webhook 會使用標準 HTTP 要求連結應用程式),但為了簡化說明,本頁將其稱為 Chat 應用程式。每個 webhook 只能在註冊的 Chat 聊天室中運作。傳入的 Webhook 可在即時訊息中運作,但只有在所有使用者已啟用 Chat 擴充應用程式時才能使用。您無法將 Webhook 發布至 Google Workspace Marketplace。
下圖顯示連線至 Chat 的 Webhook 架構:
在上圖中,Chat 應用程式含有下列資訊流:
- Chat 應用程式邏輯會從外部第三方服務 (例如專案管理系統或支援單工具) 接收資訊。
- Chat 應用程式邏輯會託管於雲端或內部系統,可透過 Webhook 網址傳送訊息至特定 Chat 聊天室。
- 使用者可以在該特定 Chat 聊天室中接收 Chat 應用程式傳送的訊息,但無法與 Chat 應用程式互動。
必要條件
Python
- 可存取 Google Chat 的 Business 或 Enterprise Google Workspace 帳戶。Google Workspace 機構必須允許使用者新增及使用連入的 Webhook。
- Python 3.6 以上版本
- pip 套件管理工具
httplib2
程式庫。如要安裝程式庫,請在指令列介面中執行下列指令:pip install httplib2
Google Chat 聊天室。如要使用 Google Chat API 建立聊天室,請參閱「建立聊天室」。如要在 Chat 中建立聊天室,請參閱說明中心說明文件。
Node.js
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。Google Workspace 機構必須允許使用者新增及使用連入的 Webhook。
- Node.js 14 或以上版本
- npm 套件管理工具
- Google Chat 聊天室。如要使用 Google Chat API 建立聊天室,請參閱「建立聊天室」。如要在 Chat 中建立聊天室,請參閱說明中心說明文件。
Java
- 具備 Google Chat 存取權的 Business 或 Enterprise Google Workspace 帳戶。您的 Google Workspace 機構必須允許使用者新增及使用連入的 Webhook。
- Java 11 以上版本
- Maven 套件管理工具
- Google Chat 聊天室。如要使用 Google Chat API 建立聊天室,請參閱「建立聊天室」。如要在 Chat 中建立這類對話,請參閱說明中心的說明文件。
Apps Script
- 具備 Google Chat 存取權的 Google Workspace 企業或進階版帳戶。您的 Google Workspace 機構必須允許使用者新增及使用連入的 Webhook。
- 建立獨立的 Apps Script 專案,然後開啟進階 Chat 服務。
- Google Chat 聊天室。如要使用 Google Chat API 建立聊天室,請參閱「建立聊天室」。如要在 Chat 中建立聊天室,請參閱說明中心說明文件。
建立 Webhook
如要建立 Webhook,請在要接收訊息的 Chat 聊天室中註冊 Webhook,然後編寫用來傳送訊息的指令碼。
註冊 incoming Webhook
- 在瀏覽器中開啟 Chat。您無法透過 Chat 行動應用程式設定 Webhook。
- 前往要新增 Webhook 的聊天室。
- 按一下聊天室名稱旁的 展開更多箭頭,然後點選「應用程式與整合」。
按一下
「Add Webhooks」(新增 Webhook)。在「Name」(名稱) 欄位中輸入
Quickstart Webhook
。在「顯示圖片網址」欄位中輸入
https://developers.google.com/chat/images/chat-product-icon.png
。按一下 [儲存]。
如要複製 Webhook 網址,請依序點選
「更多」圖示和 「複製連結」。
編寫 Webhook 指令碼
範例 Webhook 指令碼會傳送 POST
要求至 Webhook 網址,藉此將訊息傳送至註冊 Webhook 的聊天室。Chat API 會傳回 Message
的例項。
請選取語言,瞭解如何建立 Webhook 指令碼:
Python
在工作目錄中,建立名為
quickstart.py
的檔案。在
quickstart.py
中貼上以下程式碼:將
url
變數的值替換成您在註冊 Webhook 時複製的 Webhook 網址。
Node.js
在工作目錄中,建立名為
index.js
的檔案。在
index.js
中貼上以下程式碼:將
url
變數的值替換成您在註冊 Webhook 時複製的 Webhook 網址。
Java
在工作目錄中建立名為
pom.xml
的檔案。在
pom.xml
中,複製並貼上下列內容:在工作目錄中建立下列目錄結構
src/main/java
。在
src/main/java
目錄中,建立名為App.java
的檔案。在
App.java
中貼上以下程式碼:將
URL
變數的值替換成您在註冊 Webhook 時複製的 Webhook 網址。
Apps Script
在瀏覽器中前往 Apps Script。
按一下「New Project」。
貼上下列程式碼:
將
url
變數的值替換成您在註冊 Webhook 時複製的 Webhook 網址。
執行 Webhook 指令碼
在 CLI 中執行指令碼:
Python
python3 quickstart.py
Node.js
node index.js
Java
mvn compile exec:java -Dexec.mainClass=App
Apps Script
- 按一下「執行」。
執行程式碼時,Webhook 會將訊息傳送至您註冊程式碼的聊天室。
發起或回覆訊息討論串
在訊息要求主體中指定
spaces.messages.thread.threadKey
。根據您要啟動還是回覆執行緒,使用以下的threadKey
值:如要啟動執行緒,請將
threadKey
設為任意字串,但請記下這個值,才能在執行緒上發布回覆。如要回覆執行緒,請指定在啟動執行緒時設定的
threadKey
。舉例來說,如要針對使用MY-THREAD
的初始訊息發布回覆,請設定MY-THREAD
。
如果未找到指定的
threadKey
,請定義執行緒行為:回覆討論串或發起新討論串。將
messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
參數加入 Webhook 網址。傳遞這個網址參數會導致 Chat 使用指定的threadKey
尋找現有的會話串。如果找到相關的討論串,系統就會將訊息發布為該討論串的回覆。如果沒有找到,訊息就會啟動與該threadKey
相對應的新執行緒。回覆討論串或不採取任何行動。將
messageReplyOption=REPLY_MESSAGE_OR_FAIL
參數加入 webhook 網址。傳遞這個網址參數會導致 Chat 使用指定的threadKey
尋找現有的會話串。如果有找到,訊息會以回覆該討論串的形式發布。如果找不到任何內容,則不會傳送訊息。
詳情請參閱
messageReplyOption
。
以下程式碼範例會開始或回覆訊息串:
Python
Node.js
Apps Script
處理錯誤
Webhook 要求可能會因為各種原因而失敗,包括:
- 無效的要求。
- Webhook 或代管 Webhook 的空間已遭到刪除。
- 網路連線或配額限制等間歇性問題。
建構 Webhook 時,請透過下列方式妥善處理錯誤:
- 記錄失敗。
- 如果是基於時間、配額或網路連線錯誤,請以指數輪詢方式重試要求。
- 不執行任何動作 (傳送 Webhook 訊息不重要)。
Google Chat API 會以 google.rpc.Status
的形式傳回錯誤,其中包含 HTTP 錯誤 code
,用於指出發生的錯誤類型:用戶端錯誤 (400 系列) 或伺服器錯誤 (500 系列)。如要查看所有 HTTP 對應項目,請參閱 google.rpc.Code
。
{
"code": 503,
"message": "The service is currently unavailable.",
"status": "UNAVAILABLE"
}
如要瞭解如何解讀 HTTP 狀態碼和處理錯誤,請參閱「錯誤」一文。
限制和注意事項
- 在 Google Chat API 中使用 Webhook 建立訊息時,回應中不會包含完整訊息。回應只會填入
name
和thread.name
欄位。