WT Payment

Appearance

操作示範影片（含步驟字幕）

TG 機器人 ​

路徑：/admin/system/telegram  |  快捷鍵：- → ;  |  選單位置：資訊管理 → TG 機器人

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

建置教學 ​

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

步驟一：建立 Bot ​

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

安全提醒

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

步驟二：取得 Chat ID ​

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

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

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

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

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

getUpdates 回傳空陣列？

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

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

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

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

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

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

TIP

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

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

  1. 登入系統後台，進入「資訊管理 → TG 機器人」頁面
  2. 點擊「新增機器人」按鈕
  3. 填入以下資訊：
欄位說明
名稱自訂的識別名稱（例：「代付通知機器人」）
Bot Token步驟一取得的 Token
Chat ID步驟二取得的 Chat ID
通知類型勾選要啟用的通知（代付申請 / 通道額度收滿 / 當日收款上限達標）
通知範圍這隻機器人要收哪些商戶的通知（見下方通知範圍）；三種通知都沒勾時不會出現
  1. 儲存後點擊「測試」按鈕，確認 Telegram 收到測試訊息（送出前會再確認一次，避免誤觸打擾群組）

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

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

  1. 在 Telegram 私聊你的 Bot，發送 /start
  2. 在群組中，讓一位已經私聊過 Bot 的人發送任意訊息
  3. 回覆該訊息，輸入 /add_admin
  4. 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 看不到群組訊息 ​

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

機器人列表 ​

欄位說明
名稱機器人的識別名稱（自訂）
啟用啟用/停用開關，停用後不會發送任何通知
通知類型已勾選的通知項目 Badge（代付申請 / 通道額度收滿 / 當日收款上限達標），皆未勾選時顯示 -
通知範圍目前設定的範圍（全部商戶 / 自訂商戶），見下方通知範圍
Bot TokenTelegram 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

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

代付領單 ​

每隻機器人預設關閉。在「通知服務」（編輯機器人）勾選代付申請後，底下會用連接線帶出「代付領單」開關：

  1. 打開開關。系統會確認這隻機器人的 webhook 指向本站；如果指向別的主機（多個站點共用同一個 Token），會拒絕開啟，請改用本站專屬的機器人。
  2. 儲存。之後這隻機器人發的代付通知都會帶「🙋 領取」按鈕。

只能用在內部出款群組

群組裡所有人都能領取並按「已完成」，而「已完成」等於審核通過（扣商戶餘額、回調商戶已出款）。請只在只有自己人的出款群組開啟，不要在有商戶或外部人員的群組使用。

群組裡的流程：

按鈕誰可以按結果
🙋 領取群組裡任何人，第一個點到的人鎖定這張單，訊息顯示「領取人：某某」，按鈕換成「✅ 已完成」「↩️ 放棄」。其他人再點會看到「已由某某領取」
✅ 已完成只有領取人代付單審核通過並回調商戶，訊息改成「已完成：某某」並移除按鈕
↩️ 放棄只有領取人取消領取，訊息恢復「領取」按鈕
  • 已審核的單（不論在 TG 或後台處理），訊息都會改成最終狀態並保留在群組，不會被自動收回。
  • 後台處理已被領走的單、強制釋放領取，見 代付審核 → TG 代付領單。
  • 審核人會記成「TG：顯示名稱」，操作日誌另外記下按的人的 TG 帳號。
  • 領單人只有系統後台看得到：商戶後台的代付紀錄、餘額異動、站內信與商戶 API 查詢都不會顯示領單人與領取狀態（審核人一欄顯示「-」），TG 完成的單也不會寫審核備註。
  • 只認這隻機器人群組裡、系統發出的那則通知；訊息被轉傳到別的群組，按了也沒用。
  • 每次領取、放棄、完成都會寫入操作日誌。

發送紀錄：收回與置頂 ​

在機器人列表按「發送歷程」打開該 Bot 的通知發送紀錄，「代付通知」與「通道額度通知」兩個分頁都可以對已發出的訊息操作（需要 telegram.update 權限，沒有權限只能查看）：

操作說明
收回從群組刪除這則通知。同一張代付單在這個群組被補發過多則時，會一起刪除。刪除前會先確認，刪除後無法復原
批次收回勾選多列後按「收回選取」，一次最多 100 筆。表頭的勾選框可全選本頁還能收回的通知
置頂／取消置頂依目前狀態切換。置頂時不會通知群組成員
重新發送已收回或發送失敗、單還待處理且沒被 TG 領取時出現。把通知重新發到這個群組，不檢查通知範圍，確認視窗會寫出商戶與群組
  • 收回後該列顯示「已收回」，系統不會再自動補發到這個群組；需要時可按「重新發送」。
  • 操作會記錄在操作日誌（收回／置頂／取消置頂 TG 通知）。
  • 常見用途：機器人的通知範圍設錯，別的商戶的代付通知發進了這個群組。

限制

  • Telegram 只允許機器人刪除 48 小時內的訊息，更早的請到群組手動刪除。
  • 收回與置頂都需要 Bot 是群組管理員，並有「刪除訊息」「置頂訊息」權限（見上方「步驟三：設定 Bot 權限」）。
  • 訊息已經被群組成員手動刪掉時，收回會直接標記為「已收回」。

訊息模板 ​

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

代付通知模板變數 ​

變數說明範例值
{merchantCode}商戶代碼OTTEST
{merchantName}商戶名稱測試商戶
{payoutNo}代付單號PO1710000000abc
{merchantPayoutNo}商戶訂單號（商戶自帶單號，僅 API 建立的代付才有；後台建立的代付會顯示空白）M20260620001
{amount}金額（含 $ 符號）$10,000
{fee}手續費（含 $ 符號）$15
{bankCode}銀行代碼812
{bankCodeName}銀行名稱台新國際商業銀行
{branchCode}分行代碼（未填時顯示空白）0154
{bankAccount}銀行帳號12345678901234
{accountName}戶名王小明
{source}來源（API / 後台）後台
{operatorName}操作者admin
{botName}發送這則通知的機器人名稱（每隻機器人各自帶入自己的名稱）代付機器人
{createdAt}建立時間2026/6/20 下午5:30:00
{merchantDailyCount}（站點限定） 該商戶當日累積代付筆數7
{merchantDailyAmount}（站點限定） 該商戶當日累積代付金額（含 $ 符號）$168,000

{merchantDailyCount}／{merchantDailyAmount} 僅在特定站點啟用，其他站點的變數標籤與提示文字不會出現這兩個變數。

失敗補發的內容與初次發送相同

初次發送失敗、改由失敗補發送出的通知，所有變數（包含商戶訂單號、分行代碼、機器人名稱、當日累積）都會正常帶入， 內容與初次發送一致，不會出現 {branchCode} 這類沒被替換的變數。補發時的「當日累積」統計到該筆代付建立為止，與初次發送當下的數字相同。

通道額度通知模板變數 ​

變數說明範例值
{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 群組批次發送訊息，支援標籤篩選、排程發送、一鍵收回等功能。

前提條件

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

基本操作流程 ​

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

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

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

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

第二步：選擇廣播目標

Bot 會顯示標籤選項：

  • 全部群組 — 選取本站所有已綁定的群組
  • #標籤名稱 — 只選取帶有該標籤的群組

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

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

第三步：發送或排程

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

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

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

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

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

TIP

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

排程發送 ​

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

模式時間格式範例說明
📅 單次YYYY-MM-DD HH:mm2026-08-01 15:30指定日期時間發送一次
🌞 每日HH:mm15: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 與廣播都只涵蓋本站：各站點的機器人各自運作，不會查詢或轉發到其他站點的群組
  • /groups 指令只顯示當前 Bot 綁定的群組，不混入其他 Bot
  • 廣播系統的群組選取、發送紀錄、排程任務皆按 Bot 隔離

權限 ​

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

WT Payment — 金流收帳系統操作手冊 · v1.0.42