金送推廣卡片 Bot
使用說明

一開始

管理員私訊 bot 輸入 /start，就會出現主選單。

不是管理員的人輸入 /start，只會收到推廣卡片，並自動記成用戶。

👁 預覽卡片 可以先看一次卡片目前長怎樣。

每次修改後，bot 會先傳一張預覽，下面附上目前的設定摘要。不想改了就按 ✖️ 取消，會回到主選單。

二換素材（圖片／影片／GIF）

1. 按 🖼 素材
2. 直接傳一張圖片、一支影片或一個 GIF 給 bot
3. 按 🗑 改成純文字 可以拿掉素材

傳素材時帶的說明文字，會一起變成新的文案。
轉發「頻道貼文」給 bot 是用來新增頻道的，不會蓋掉素材。

相簿模式（10-27 新增）

按 🖼 素材 → 🗂 相簿模式（2–10 張），連續傳 2–10 張圖片或影片，再按 ✅ 完成。

Telegram 的相簿不能帶按鈕，bot 會在相簿後面自動補一則帶按鈕的訊息；那句話可用 ✏️ 相簿按鈕文字 改。

三改文案

1. 按 ✏️ 文案
2. 傳一段文字給 bot

字數上限

超過的話，bot 會告訴你還要刪幾個字，不會存進去。

四設定按鈕

1. 按 🔘 按鈕
2. 一行寫一個按鈕，格式是 文字 - 網址；想放在同一排，就用 | 隔開
3. 按鈕要上色：結尾加 #紅、#綠 或 #藍，例如 點擊領取 - https://… #紅

點擊領取專屬福利 - https://gsgs888.vip?proxy=fwfuz9
客服 - https://t.me/xxx | 官網 - https://gsgs888.vip

預設按鈕

ad0017 註冊頁 https://gsgs888.vip?proxy=fwfuz9

追蹤

發送出去的按鈕網址，會自動換成追蹤連結 tgp.gaifun.com/r/…，點擊後記錄一次，再轉到真正的網址。

五特效

按 ✨ 特效 開關，可以隨時切換。

模糊遮罩和文字在上方，要有素材才有效果。

六廣告庫

可以同時存多張卡片。素材、文案、按鈕、特效的所有編輯，都是改「目前編輯中」的那一張。

📚 廣告庫

列出所有卡片，點進去可 🎯 設為目前編輯、👁 預覽卡片、✏️ 改名、📑 複製、🗑 刪除（會再確認一次）。

➕ 新增卡片

可選 📄 空白卡片 或 📑 複製目前編輯中的卡片。

輪播開關

打開的卡片才會參與排程的「輪播」模式（見 排程）。

命令列也能加卡片：newcard.py 圖片 文案 --new 名稱。

七頻道

三種方式新增（擇一）

A　設管理員

把 bot 設成頻道／群組的管理員（要有發文權限），會自動加入清單。

B　轉發貼文

從頻道轉發任何一則貼文給 bot。

C　手動輸入

按 📢 頻道 → 新增，輸入 @頻道名稱 或 -100 開頭的 ID。貼 t.me/xxx 也可以，會自動轉成 @xxx。

刪除頻道

在清單點頻道 → 刪除 → 再按一次確認。

發新刪舊／置頂（10-27 新增）

按 📢 頻道 → 點某個頻道，可以分別打開「發新刪舊」（新的一則發出後，自動刪掉上一則）和「自動置頂」。

bot 需要該頻道的「刪除訊息」「置頂訊息」權限。沒有權限不影響發送，只會在發送回報裡提示。

八發送

分兩步驟，避免按錯。

1. 按 🚀 發送，勾選目標：各頻道、全選頻道、👥 私訊所有用戶（N 人）
2. 按 下一步 ➡️（已選 N），確認畫面會列出要發給誰、大概要多久
3. 按 ✅ 確認發送 才會真的發出去

發送期間會鎖住，重複點也不會發兩次。發完會顯示成功／失敗的數量。

九排程

每天固定時間（台北時間）自動發，不用人手按。

1. 按 ⏰ 排程 → ➕ 新增排程，輸入時間（例如 21:30）
2. 🎯 選目標：要發到哪些頻道，跟手動發送一樣勾選
3. 🔁 選模式：🔁 輪播（依序下一張啟用中的卡），或固定發某一張卡片
4. 新排程預設是停用，確認沒問題後再按啟用；想先看效果可按 🧪 立即測試發一次

每次排程發完，bot 會私訊管理員一則摘要（成功／失敗數）。時間可用 ⏱ 改時間 改。

十關鍵字

群組裡有人的訊息含有設定的關鍵字，bot 就自動回覆卡片。按 💬 關鍵字 → ➕ 新增關鍵字，可指定回哪一張卡片；冷卻時間預設 60 秒，可改。

1. 到 BotFather → /setprivacy → 選這個 bot → Disabled（或直接把 bot 設成群組管理員）
2. 改完隱私設定後，要把 bot 踢出群組再重新加入才會生效

十一統計

按 📊 統計 可看各頻道、各卡片的今日／7 天點擊，加上 24 小時長條圖與高峰時段；每一次發送都有編號，可看每則、每個按鈕的點擊數。按 📥 匯出 CSV 可以拿到點擊明細（含頻道與卡片欄位），檔案會直接傳給你。

網頁版數據（10-28 新增）

在統計選單按 🌐 網頁版數據，會開啟一頁手機也好看的數據頁：今日／7 天／30 天／累計點擊、近 14 天趨勢、今日 24 小時分佈、各頻道、各卡片、最近發送與最近點擊。

網址形式是 tgp.gaifun.com/?k=金鑰，金鑰放在設定檔的 STATS_KEY。這個連結等於看數據的鑰匙，不要貼到公開的地方；要換鑰匙就改 STATS_KEY 後重啟 bot。

追蹤模式（設定檔的 TRACK_MODE）

count

只算次數，用 IP+UA 去重。目前用這個。

login

用 TG 登入，記得是誰點的。要先到 BotFather 用 /setdomain 設定 tgp.gaifun.com。

十二用戶

私訊過 bot 的人會自動記住，可以看人數和名單，按 📥 匯出 CSV 能匯出。

封鎖 bot 的人在群發時會自動跳過；之後重新開啟 bot 會自動解除。

十三Inline 模式

在任何聊天室都能叫出卡片：

1. 在輸入框打 @gx_jinsong_fuli_bot，後面加一個空格
2. 上方會跳出卡片，點一下就送出（附帶按鈕）

這樣送出的卡片，點擊不會記進統計。

十四維運（Mac）

程式資料夾 ~/tg-promo-bot

bot.py

主程式

card.json

目前的卡片設定

data.db

頻道／點擊／發送紀錄／用戶

.env

Token 與設定 不要外傳

assets/avatar.jpg

bot 頭貼

logs/bot.log

日誌

常駐（開機會自動啟動）

launchctl kickstart -k gui/$(id -u)/com.tgpromo.bot

launchctl kickstart -k gui/$(id -u)/com.tgpromo.tunnel

tail -f ~/tg-promo-bot/logs/bot.log

curl -I https://tgp.gaifun.com/r/<編號>/0

十五常見問題