TG 機器人

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

管理 Telegram 通知機器人，支援代付申請通知、通道額度收滿通知、群組指令查詢、廣播群發等功能。

建置教學

本節說明如何從零開始建立 Telegram Bot 並接入系統，完成後即可使用通知、指令、廣播等功能。

步驟一：建立 Bot

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

安全提醒

Bot Token 等同密碼，請勿外洩。若懷疑 Token 已洩漏，請立即到 BotFather 使用 /revoke 重新產生。

步驟二：取得 Chat ID

你需要知道通知要發送到哪裡。根據使用場景選擇以下方式：

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

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

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

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

getUpdates 回傳空陣列？

如果 Bot 是後加入群組的，需要先在群組中 @你的Bot 發送一條訊息，getUpdates 才能取得到群組的 Chat ID。

若仍然為空，請到 BotFather 執行 /setprivacy → 選擇你的 Bot → Disable，然後將 Bot 移出群組再重新加入。

步驟三：設定 Bot 權限（建議）

為了讓 Bot 的所有功能（廣播、置頂、收回訊息等）正常運作，建議將 Bot 設為群組管理員，並開啟以下權限：

權限	用途
發送訊息	廣播群發、通知發送
刪除訊息	一鍵收回廣播、代付審核後自動收回
置頂訊息	通道額度收滿通知自動置頂

設定方式：群組設定 → 管理員 → 選擇你的 Bot → 開啟上述權限

TIP

如果只需要接收通知（不需要置頂和收回），Bot 不需要管理員權限也能正常發送訊息。

步驟四：在系統中新增機器人

登入系統後台，進入「系統管理 → TG 機器人」頁面
點擊「新增機器人」按鈕
填入以下資訊：

欄位	說明
名稱	自訂的識別名稱（例：「代付通知機器人」）
Bot Token	步驟一取得的 Token
Chat ID	步驟二取得的 Chat ID
通知類型	勾選要啟用的通知（代付申請 / 通道額度收滿 / 當日收款上限達標）
通知範圍	這隻機器人要收哪些商戶的通知（見下方通知範圍）；三種通知都沒勾時不會出現

儲存後點擊「測試」按鈕，確認 Telegram 收到測試訊息（送出前會再確認一次，避免誤觸打擾群組）

步驟五：設定指令管理員（廣播功能需要）

如果要使用廣播功能，需要先設定指令管理員：

在 Telegram 私聊你的 Bot，發送 /start
在群組中，讓一位已經私聊過 Bot 的人發送任意訊息
回覆該訊息，輸入 /add_admin
Bot 會回覆確認，該使用者即成為指令管理員

TIP

第一位管理員需要有人幫忙加入。一旦成為管理員後，就可以自行用 /add_admin 新增其他管理員。如果目前沒有任何管理員，則所有人都有管理員權限（預設開放）。

常見問題

Bot 發送測試訊息失敗

確認 Bot Token 是否正確（到 BotFather 用 /token 查詢）
確認 Chat ID 格式正確（個人 ID 為正數，群組 ID 以 - 開頭）
確認 Bot 已加入目標群組

廣播「成功：0 | 失敗：N」

chat not found — Chat ID 不正確或 Bot 已被踢出群組，請到群組列表中刪除無效的群組
not enough rights — Bot 沒有發送訊息的權限，請將 Bot 設為群組管理員
fetch failed — Server 端網路問題，無法連線到 Telegram API

通知置頂不生效

Bot 需要在群組中被設為管理員，並開啟「置頂訊息」權限。通知發送不受此影響。

getUpdates 看不到群組訊息

到 BotFather 執行 /setprivacy → 選擇你的 Bot → Disable
將 Bot 移出群組再重新加入
在群組中發送訊息後再查詢 getUpdates

機器人列表

欄位	說明
名稱	機器人的識別名稱（自訂）
啟用	啟用/停用開關，停用後不會發送任何通知
通知類型	已勾選的通知項目 Badge（代付申請 / 通道額度收滿 / 當日收款上限達標），皆未勾選時顯示 `-`
通知範圍	目前設定的範圍（同指令服務 / 全部商戶 / 自訂商戶），見下方通知範圍
Bot Token	Telegram Bot 的 API Token（部分遮罩顯示）
Chat ID	通知目標的 Telegram Chat ID
操作	發送歷程、測試、編輯、刪除

操作按鈕

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

通知功能

代付申請通知

代付訂單（API 或後台）建立時自動發送通知到指定的 Telegram 群組或個人聊天。

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

訊息收回邏輯（依站點不同）

部分站點：審核駁回時自動收回通知訊息；審核通過時保留訊息不收回，方便留存紀錄。

其他站點：審核完成後（無論核准或駁回），訊息一律自動從群組中收回刪除。

通道額度收滿通知

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

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

置頂功能需要管理員權限

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

當日收款上限達標通知

當商戶的某個付款方式當日收款金額達到設定的 當日收款上限、系統自動關閉該付款方式時，發送警報通知。

需先在商戶資料管理為該商戶的支付方式設定當日收款上限
發送成功後會 自動置頂 訊息
訊息中會標示「已自動關閉該付款方式，隔日 00:00 自動重新啟用」
發送失敗會自動重試（最多 3 次，間隔 2 秒）

通知範圍

一隻機器人不一定要收全站的通知。通知範圍設定這隻機器人要收哪些商戶的通知，三選一，且三種通知共用同一個範圍（代付申請 / 通道額度收滿 / 當日收款上限達標）：

選項	說明
同「指令服務」的商戶綁定	跟著該群組指令服務綁定的商戶走，綁定改了通知範圍自動跟著改
全部商戶	收全站所有商戶的通知
自訂商戶	自己挑要收哪幾個商戶

「同指令服務」是給「一個群組一個客戶」用的：那種情況下，群組能查的商戶與該收到的通知本來就是同一批，選這個就不必在兩個地方各維護一份名單、也不會改了一邊忘了另一邊。選項旁邊會直接寫出現在等於哪些商戶，不必跳到指令服務彈窗去查。

三種通知全都沒勾時這個設定會收起來 —— 沒有任何通知會發出去，範圍也就無從談起。

通知觸發時機

通知類型	觸發事件	後續行為
代付申請	API 或後台建立代付訂單	審核完成後自動收回訊息
通道額度收滿	定時重置模式通道全部收滿	自動置頂（需管理員權限）
當日收款上限達標	商戶某付款方式當日收款達上限	自動關閉該付款方式並置頂通知，隔日 00:00 自動重啟

TIP

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

訊息模板

點擊「訊息模板」下拉按鈕可分別設定各種通知的訊息格式。模板編輯器提供即時預覽功能，可在儲存前確認格式是否正確。點擊「重置預設」可恢復系統預設模板。

代付通知模板變數

變數	說明	範例值
`{merchantCode}`	商戶代碼	OTTEST
`{merchantName}`	商戶名稱	測試商戶
`{payoutNo}`	代付單號	PO1710000000abc
`{merchantPayoutNo}`	商戶訂單號（商戶自帶單號，僅 API 建立的代付才有；後台建立的代付會顯示空白）	M20260620001
`{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

當日上限通知模板變數

變數	說明	範例值
`{merchantCode}`	商戶代碼	OTTEST
`{merchantName}`	商戶名稱	測試商戶
`{paymentMethod}`	付款方式	超商代碼
`{currentAmount}`	當日已收金額（含 $ 符號）	$100,000
`{dailyLimit}`	當日上限（含 $ 符號）	$100,000
`{action}`	後續處理說明	已自動關閉該付款方式，隔日 00:00 自動重新啟用
`{botName}`	機器人名稱	警報機器人
`{time}`	通知時間	2026/6/20 下午5:30:00

指令服務

Telegram Bot 支援在群組或私聊中使用斜線指令，即時查詢系統資訊。

可用指令

指令	說明	權限
`/start`	私聊時顯示歡迎訊息與功能按鈕；群組中回覆群組 ID	所有人
`/balance`	查詢各商戶通道餘額摘要	所有人
`/pending`	查詢待撥款總金額（統計所有未撥款訂單）	所有人
`/groups`	列出所有站點已綁定的群組	所有人
`/admin`	查看目前的管理員名單	所有人
`/add_admin`	新增指令管理員（回覆目標使用者的訊息）	僅管理員
`/del_admin`	移除指令管理員	僅管理員

指令管理員

指令管理員（Command Admin）是指有權執行進階管理指令和操作廣播系統的 Telegram 使用者：

透過 /add_admin 指令新增（回覆目標使用者的訊息即可）
透過 /del_admin 指令移除
/admin 指令列出目前的管理員清單
僅有私聊 /start 過的使用者可被加為管理員

私聊功能

歡迎訊息：私聊 /start 會顯示歡迎訊息與底部常駐鍵盤（群組列表、發送紀錄、標籤總覽、排程任務）
訊息轉發：私聊 Bot 的非指令訊息會觸發廣播流程（見下方「廣播系統」）
群組列表導航：支援瀏覽所有綁定群組的詳細資訊

廣播系統

廣播系統用於向多個 Telegram 群組批次發送訊息，支援標籤篩選、排程發送、一鍵收回等功能。

前提條件

Bot 必須已加入目標群組，且為群組管理員（需有「發送訊息」權限）
操作者必須是指令管理員（透過 /add_admin 新增）
Bot 必須已綁定至少一個群組

基本操作流程

第一步：私聊 Bot 發送要廣播的內容

在 Telegram 中私聊你的 Bot，直接發送訊息。支援的內容類型：

類型	說明
文字	直接輸入文字訊息
圖片	發送圖片（含圖說）
影片	發送影片
檔案	發送文件附件
音檔	發送音訊檔案
語音	發送語音訊息
貼圖	發送貼圖

發送後，Bot 會跳出標籤選擇按鈕。

第二步：選擇廣播目標

Bot 會顯示標籤選項：

全部群組 — 選取所有已綁定的群組（含跨站群組）
#標籤名稱 — 只選取帶有該標籤的群組

選擇標籤後，進入群組勾選畫面，可以逐一勾選/取消特定群組。

按鈕	說明
✅ 群組名稱	已選取（點擊可取消）
⬜ 群組名稱	未選取（點擊可選取）
全部選取	勾選所有群組
全部取消	取消所有勾選

第三步：發送或排程

勾選完群組後，可以選擇：

按鈕	說明
🚀 立即發送	馬上群發到所有已選群組
⏰ 排程發送	設定未來時間定時發送（見下方排程說明）
❌ 取消廣播	取消本次操作

發送完成後會顯示結果：✅ 完成！成功：N | 失敗：N

第四步：一鍵收回（選用）

發送完成後，結果訊息下方會出現「🗑️ 一鍵收回」按鈕，點擊後會從所有群組中刪除剛才發送的訊息。

TIP

收回資料會保留 24 小時，超過後無法再收回。

排程發送

選擇「⏰ 排程發送」後，可選擇排程模式：

模式	時間格式	範例	說明
📅 單次	`YYYY-MM-DD HH:mm`	`2026-08-01 15:30`	指定日期時間發送一次
🌞 每日	`HH:mm`	`15:30`	每天固定時間發送
🗓️ 每週	`週X,週X HH:mm`	`週一,週三 15:30`	每週指定日固定時間發送

排程建立後可透過底部鍵盤的「⏰ 排程任務」按鈕查看和管理所有排程。

群組管理

點擊底部鍵盤的「📋 群組列表」可以管理所有綁定的群組：

查看群組詳情 — 顯示群組 ID 和已設定的標籤
標籤管理 — 為群組新增/移除標籤，方便廣播時快速篩選
新增自定義標籤 — 輸入任意標籤名稱
刪除群組 — 從綁定列表中移除群組

標籤總覽

點擊底部鍵盤的「🏷️ 標籤總覽」可以查看所有標籤及其對應的群組分佈。

發送紀錄

點擊底部鍵盤的「📜 發送紀錄」可以查看歷史廣播紀錄，包含發送時間、內容摘要、成功/失敗數量和目標群組。

底部常駐鍵盤

私聊 Bot 發送 /start 後，底部會出現常駐功能鍵盤：

按鈕	說明
📋 群組列表	管理綁定群組與標籤
📜 發送紀錄	查看歷史廣播紀錄
🏷️ 標籤總覽	查看所有標籤分佈
⏰ 排程任務	查看和管理排程廣播

發送歷程（後台）

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

代付通知 Tab

欄位	說明
代付單號	代付訂單編號
金額	代付金額
訂單狀態	PENDING / SUCCESS / REJECTED
通知狀態	已通知（綠色）/ 未通知（紅色）。已發送但事後被收回的訊息會另外標上「已收回」
發送時間	訂單建立時間

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

「已收回」與「未通知」是兩回事

「已收回」代表訊息確實發送成功過，只是審核完成後依規則從群組裡刪掉了；「未通知」則是根本沒發出去。兩者在對帳與追查時的意思完全不同，所以分開標示。

舊資料查不到

這份紀錄過去是與「待收回佇列」共用同一份資料，每筆代付一經審核就會被清空，所以審核完成的單幾乎都查不到發送紀錄。現已改為獨立保存的歷程，之後的發送都留得下來 —— 但在此之前已經被清掉的紀錄無法復原。

通道額度通知 Tab

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

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

自動機制

機制	頻率	說明
失敗補發	每 5 分鐘	自動補發 5~60 分鐘內發送失敗的代付通知，每個 Chat ID 最多重試 3 次。補發一樣會套用通知範圍，不會把某個商戶的代付單補發到不該收的群組
審核收回	即時	代付審核完成後立即刪除對應的 TG 通知訊息
批次收回	每 2 分鐘	自動掃描 24 小時內已審核但訊息未收回的代付，批次刪除
排程廣播	每分鐘	檢查是否有到期的排程廣播任務，自動執行發送

多 Bot 隔離

每個 Bot 的群組列表獨立
/groups 指令只顯示當前 Bot 綁定的群組，不混入其他 Bot
廣播系統的群組選取、發送紀錄、排程任務皆按 Bot 隔離

權限

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

TG 機器人 ​

建置教學 ​

步驟一：建立 Bot ​

步驟二：取得 Chat ID ​

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

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

步驟三：設定 Bot 權限（建議） ​

步驟四：在系統中新增機器人 ​

步驟五：設定指令管理員（廣播功能需要） ​

常見問題 ​

Bot 發送測試訊息失敗 ​

廣播「成功：0 | 失敗：N」 ​

通知置頂不生效 ​

getUpdates 看不到群組訊息 ​

機器人列表 ​

操作按鈕 ​

通知功能 ​

代付申請通知 ​

通道額度收滿通知 ​

當日收款上限達標通知 ​

通知範圍 ​

通知觸發時機 ​

訊息模板 ​

代付通知模板變數 ​

通道額度通知模板變數 ​

當日上限通知模板變數 ​

指令服務 ​

可用指令 ​

指令管理員 ​

私聊功能 ​

廣播系統 ​

基本操作流程 ​

排程發送 ​

群組管理 ​

標籤總覽 ​

發送紀錄 ​

底部常駐鍵盤 ​

發送歷程（後台） ​

代付通知 Tab ​

通道額度通知 Tab ​

自動機制 ​

多 Bot 隔離 ​

權限 ​