← 所有文章
指南

Telegram Bot 深層連結:處理 start 參數與帳戶綁定

Telegram Bot 深層連結會透過私人對話的 /start 指令傳入參數,但單靠它不能證明網站帳戶與 Telegram 用戶屬於同一人。應用參數查找伺服器上的待處理請求,等待機械人實際收到更新,再明確確認敏感的帳戶綁定。開啟網址不等於完成綁定。

重點

  • 啟動參數最多 64 個字元,可用英文字母、數字、底線及連字號。
  • start 是私人對話入口;startgroup 是另一套加入群組流程。
  • 推廣來源代碼可以公開;帳戶綁定權杖應不可預測、短期有效,而且只可使用一次。
  • 啟動機械人與授權現有 Telegram 訊息帳戶,是兩種不同的整合。

Telegram start 連結實際傳送甚麼

Telegram 的機械人功能文件介紹了深層連結,包括將 Telegram 用戶與其他平台帳戶關聯的用途。網址語法為 https://t.me/<bot_username>?start=<parameter>。尖括號內容只用作語法說明,不是可用機械人或正式環境權杖。

用戶端深層連結規格說明,Start 按鈕會帶同參數執行啟動操作。因此,介面應根據實際收到的指令推進,而不是根據瀏覽器點擊或假定自動發出的訊息。機械人會收到類似 /start airplane 的文字,這裏沿用 Telegram 官方範例參數。

參數容許 A-Z、a-z、0-9、_ 和 -,最多 64 個字元。Telegram 建議用 base64url 編碼二進位等內容。但編碼不是加密,也不能建立信任。不要把密碼、bot token、API hash、電郵地址或可重複使用的登入憑證放進網址。

加入群組的入口另有 startgroup 規格。不要把群組指令當成私人帳戶綁定的證明。

將路由與身份驗證分開

用途建議參數收到參數可以說明甚麼
開啟說明主題公開且在允許清單內的主題代碼用戶要求該主題
記錄推廣入口公開推廣代碼一次來源歸因,不是已驗證身份
綁定已登入網站帳戶不透明、單次使用的伺服器端參照一項仍待確認的關聯

用戶可以手動輸入指令或轉發網址。因此,參數中有客戶編號,不代表發送者擁有該客戶記錄。即使權杖不可預測,也可能被轉發或洩露;隨機性本身不能證明兩端帳戶是預期的配對。

若不清楚憑證的分別,先閱讀 Telegram API ID、API hash 與 bot token 比較。啟動參數只是應用程式輸入,不是上述憑證。

建議的帳戶綁定流程

以下是應用程式設計建議,不是 Telegram 提供的權杖服務,也不是新增的 UnifyPort 端點。

  1. 從已登入的網站工作階段發起。 顯示將會綁定的帳戶,要求用戶主動操作,並使用網站既有的工作階段及防請求偽造措施。
  2. 在伺服器建立待處理請求。 產生密碼學安全、適合網址使用的隨機權杖。儲存其雜湊值、目標網站帳戶、目標機械人、用途、到期時間及待處理狀態。這些是建議的本地記錄,不是 Telegram API 欄位。有效期由風險政策決定,Telegram 的參數格式不會替應用程式設定期限。
  3. 接收並驗證真正的更新。 驗證接收入口,只處理目標機械人的私人對話訊息,準確解析 /start 指令及檢查參數長度和字元。採用訊息中的發送者身份,不採用參數自行提供的 ID。Bot API 參考定義了 Update 和 Message 物件。
  4. 先認領,不直接授權。 以原子操作將待處理請求關聯至觀察到的 Telegram 用戶。拒絕過期請求,以及權杖被認領後由其他用戶提出的嘗試。不要向未確認的 Telegram 發送者透露網站帳戶詳情。
  5. 回到原網站工作階段確認。 顯示擬關聯的 Telegram 身份,請已登入的帳戶持有人批准。身份不符時取消請求,不要覆寫現有綁定。敏感流程亦應在 Telegram 端加入適當確認。
  6. 只提交一次,保留最少必要審計記錄。 權杖最終使用與帳戶關聯應以原子方式完成。重複投遞或再次按 Start 不得新增綁定、轉移關聯或重複發放權益。解除綁定應是獨立的已認證操作。

不要讓原始權杖進入分析工具、日誌、截圖或客服工單。限制無效嘗試頻率;若用戶一直沒有確認,就讓請求到期,不授予存取權。

按缺失環節排查

現象接着檢查
連結開啟,卻沒有指令機械人用戶名稱、Start 操作及更新接收流程
只收到 /start提供一般引導,不從缺失參數推斷帳戶
參數無效或過期請用戶從已登入網站重新發起
同一更新再次到達沿用已儲存結果,不重複綁定
不同用戶提交已認領權杖拒絕並提供新流程,不自動轉移關聯
機械人收到指令,網站仍在等待檢查應用程式的認領及確認狀態

接收方式可參考 Bot API webhook 與統一入站 webhook 比較。輪詢或 webhook 都不能代替身份確認。

UnifyPort 的適用範圍

上述啟用流程屬於官方 Telegram Bot。UnifyPort 的 Telegram 授權參考記錄的則是透過非官方介面連接現有帳戶的驗證碼、二維碼及工作階段匯入流程。啟動參數不會授權該帳戶,也不能代替帳戶持有人的批准。

如果目標是接收現有訊息帳戶的對話,請使用該授權流程及 message.received 事件。不要假設機械人深層連結會進入已連接普通帳戶的收件箱。即使後續客服同時涵蓋 WhatsApp、LINE 或 Zalo,身份綁定仍應由應用程式獨立管理。

常見問題

開啟網址就完成綁定了嗎?

不是。必須等待機械人指令及應用程式的確認交易。點擊本身不能證明訊息已收到或帳戶擁有權。

start 參數可以放客戶 ID 嗎?

可以作非敏感路由輸入,但不能作授權依據。帳戶綁定應採用隨機伺服器端參照,並明確確認。

base64url 能保護秘密嗎?

不能,它只是編碼。敏感資料應留在伺服器;權杖使用或到期前,綁定網址都應視為敏感資料。

這等同於 Telegram 用戶帳戶登入嗎?

不等同。啟動機械人不會建立已授權的用戶工作階段。請按應用程式需要的身份選擇整合方式。

下一步及參考資料

先閱讀 Telegram 的深層連結規格,再測試缺失參數、轉發網址、過期、重複更新、身份衝突及取消。這些是建議驗收項目,不是已執行的測試結果。

官方資料核對日期:2026-11-10。

UnifyPort API

令訊息接入變成一條穩定嘅產品管線。

先用統一嘅 API 跑通發送,再用標準事件將所有入站訊息接返去業務系統。