TG 機器人

路徑：/admin/system/telegram | 選單位置：系統管理 → TG 機器人

管理 Telegram 通知機器人，支援代付申請通知與通道額度收滿通知，自動發送到指定的 Telegram 群組或個人聊天。

功能概覽

支援新增多個 Telegram Bot，可各自設定通知對象
代付申請通知：代付建立時自動發送，審核完成後自動收回訊息
通道額度收滿通知：所有通道額度收滿時自動發送並置頂（需 Bot 管理員權限）
支援自訂通知訊息模板（代付 / 通道額度各一組）
發送失敗自動重試（每 5 分鐘補發，最多 3 次）
多實例部署安全：Redis 分散式鎖防止重複發送

建置 Telegram Bot

步驟一：建立 Bot

在 Telegram 搜尋並開啟 @BotFather
輸入 /newbot 開始建立機器人
依照指示輸入機器人的名稱（顯示名稱）和 username（需以 bot 結尾，例：my_notify_bot）
建立成功後，BotFather 會回覆一組 Bot Token（格式如 123456789:ABCdef...），請複製保存

步驟二：取得 Chat ID

方法 A：個人聊天（僅自己收到通知）

在 Telegram 搜尋並開啟 @userinfobot
發送任意訊息，機器人會回覆你的 Chat ID（純數字）

方法 B：群組聊天（多人收到通知，推薦）

建立一個 Telegram 群組，並將你的 Bot 加入群組
在群組中發送任意訊息，然後在瀏覽器開啟：https://api.telegram.org/bot{你的Token}/getUpdates
在回傳的 JSON 中找到 chat.id（群組 ID 通常以 -100 開頭），即為 Chat ID

注意

如果 Bot 是後加入群組的，需要先在群組中 @你的Bot 發送一條訊息，getUpdates 才能取得到群組的 Chat ID。若 getUpdates 回傳空陣列，請先到 BotFather 執行 /setprivacy → 選擇你的 Bot → Disable，然後將 Bot 移出群組再重新加入。

步驟三：在系統中設定

進入「系統管理 → TG 機器人」頁面
點擊「新增機器人」按鈕
填入名稱、Bot Token、Chat ID，勾選要啟用的通知類型
儲存後點擊「測試」按鈕確認是否收到訊息

機器人列表

欄位	說明
名稱	機器人的識別名稱（自訂）
啟用	啟用/停用開關，停用後不會發送任何通知
通知類型	已勾選的通知項目（代付申請 / 通道額度收滿）
Bot Token	Telegram Bot 的 API Token（部分遮罩顯示）
Chat ID	通知目標的 Telegram Chat ID
操作	發送歷程、測試、編輯、刪除

通知類型

代付申請

代付訂單（API 或後台）建立時自動發送通知。審核完成後（無論核准或駁回），訊息會自動從群組中收回刪除。

通知訊息中的單號會自動轉為可點擊的超連結，直接跳轉代付審核頁面
同一 Chat ID 不會重複發送
發送失敗會自動重試（每 5 分鐘，最多 3 次）

通道額度收滿

當商戶的某付款方式下所有通道額度全部收滿時自動發送通知。

僅限「定時重置」模式的通道：「不重置」模式的通道收滿後會自動歸零重新收款，不需要人工介入，因此不發通知
自動置頂：發送成功後會自動置頂訊息，方便即時注意

置頂功能需要管理員權限

通知本身不受權限影響，皆會正常發送。但自動置頂功能需要將 Bot 設為群組管理員並授予「置頂訊息」權限，否則置頂不會生效。

操作按鈕

按鈕	權限	說明
訊息模板	`telegram.update`	下拉選單，可分別設定代付通知 / 通道額度通知的訊息模板
建置教學	-	開啟完整的 Bot 建置教學彈窗
新增機器人	`telegram.create`	新增一個 Telegram Bot
發送歷程	`telegram.read`	查看該 Bot 的通知發送紀錄
測試	`telegram.update`	發送測試訊息確認 Bot 連線正常
編輯	`telegram.update`	修改 Bot 的設定
刪除	`telegram.delete`	刪除該 Bot

發送歷程

點擊機器人操作列的「歷程」圖示開啟發送歷程彈窗，內含兩個 Tab：

代付通知 Tab

顯示該機器人 Chat ID 相關的代付通知發送紀錄：

欄位	說明
代付單號	代付訂單編號
金額	代付金額
訂單狀態	PENDING / SUCCESS / REJECTED
通知狀態	已通知（綠色）/ 未通知（紅色）
發送時間	訂單建立時間

支援依代付單號搜尋，以及依通知狀態（全部/已通知/未通知）篩選。

通道額度通知 Tab

顯示該機器人 Chat ID 相關的通道額度收滿通知紀錄：

欄位	說明
摘要	商戶代碼 / 付款方式 / 通道名稱
機器人	發送的 Bot 名稱
通知狀態	已通知（綠色）/ 未通知（紅色）
置頂	已置頂（藍色）/ 未置頂（灰色）
發送時間	通知發送時間

支援依關鍵字（商戶代碼）搜尋，以及依通知狀態篩選。

訊息模板

點擊「訊息模板」下拉按鈕可分別設定兩種通知的訊息格式。

代付通知模板

變數	說明	範例值
`{merchantCode}`	商戶代碼	OTTEST
`{merchantName}`	商戶名稱	測試商戶
`{payoutNo}`	代付單號	PO1710000000abc
`{amount}`	金額（含 $ 符號）	$10,000
`{fee}`	手續費（含 $ 符號）	$15
`{bankCode}`	銀行代碼	812
`{bankAccount}`	銀行帳號	12345678901234
`{accountName}`	戶名	王小明
`{source}`	來源（API / 後台）	後台
`{operatorName}`	操作者	admin
`{createdAt}`	建立時間	2026/6/20 下午5:30:00

通道額度通知模板

變數	說明	範例值
`{merchantCode}`	商戶代碼	OTTEST
`{merchantName}`	商戶名稱	測試商戶
`{paymentMethod}`	付款方式	超商代碼
`{vendorName}`	最後通道名稱	OMGpay 測試通道
`{accumulated}`	已收金額（含 $ 符號）	$1,000
`{amountLimit}`	額度上限（含 $ 符號）	$1,000
`{action}`	後續處理說明	暫停收款，等待 00:00 自動重置
`{time}`	通知時間	2026/6/20 下午5:30:00

模板編輯器提供即時預覽功能，可在儲存前確認格式是否正確。點擊「重置預設」可恢復系統預設模板。

通知觸發時機

通知類型	觸發事件	後續行為
代付申請	API 或後台建立代付訂單	審核完成後自動收回訊息
通道額度收滿	定時重置模式通道全部收滿	自動置頂（需管理員權限）

TIP

「不重置」模式的通道收滿後會自動歸零並重新開始收款，不會觸發通道額度收滿通知。

自動機制

機制	頻率	說明
失敗補發	每 5 分鐘	自動補發 5~60 分鐘內發送失敗的代付通知，每個 Chat ID 最多重試 3 次
審核收回	即時	代付審核完成後立即刪除對應的 TG 通知訊息
批次收回	每 2 分鐘	自動掃描 24 小時內已審核但訊息未收回的代付，批次刪除

所有定時任務皆使用 Redis 分散式鎖，確保多實例部署時不會重複執行。

權限

權限代碼	說明
`telegram.read`	查看 TG 機器人頁面、發送歷程
`telegram.create`	新增機器人
`telegram.update`	編輯機器人、測試、訊息模板設定
`telegram.delete`	刪除機器人

TG 機器人 ​

功能概覽 ​

建置 Telegram Bot ​

步驟一：建立 Bot ​

步驟二：取得 Chat ID ​

步驟三：在系統中設定 ​

機器人列表 ​

通知類型 ​

代付申請 ​

通道額度收滿 ​

操作按鈕 ​

發送歷程 ​

代付通知 Tab ​

通道額度通知 Tab ​

訊息模板 ​

代付通知模板 ​

通道額度通知模板 ​

通知觸發時機 ​

自動機制 ​

權限 ​