本頁提供接入結構和實施原則，不寫死可能變化的接口地址或字段。正式開發時請以 Potato 當前官方 Bot API 手冊為準。
API 概述
Bot API 是面向機器人開發者的 HTTPS 接口。你的服務器接收用户交互，執行業務邏輯，再通過 API 向私聊、羣組或頻道返回內容。
- 適合通知、客服、查詢和自動化工具
- 支持消息、命令、按鈕和內聯交互
- 機器人憑證應只保存在受控服務端
- 用户必須先發起會話或添加機器人
接入準備
1. 創建機器人
按 Potato 當前機器人創建流程設置名稱、用户名和簡介，並獲取授權令牌。
2. 準備 HTTPS 服務
部署穩定的服務端，用於接收更新、校驗參數、執行任務併發送響應。開發、測試和生產環境應隔離。
3. 管理配置
令牌、回調密鑰和環境參數通過密鑰管理或環境配置注入，禁止提交到代碼倉庫。
// 概念示例：實際字段和方法以官方文檔為準 const update = verifyIncomingRequest(request) const command = parseCommand(update.message) const result = await runBusinessLogic(command) await potatoBot.sendMessage(update.chatId, result)
處理更新
將每個更新視為可能重複、延遲或亂序到達的事件。使用更新標識去重，為耗時任務設置隊列，並在超時後安全重試。
- 先驗證來源、格式和必要字段。
- 快速確認請求，把耗時操作交給後台任務。
- 記錄事件標識、結果和錯誤，但避免記錄敏感正文。
- 對同一用户、羣組和接口設置合理限流。
常用能力
| 能力 | 典型用途 | 實施要點 |
|---|---|---|
發送消息 | 通知、回覆、結果輸出 | 處理格式、長度和發送失敗 |
命令 | /start、/help 與業務指令 | 參數校驗與權限檢查 |
回調按鈕 | 設置、翻頁、確認操作 | 避免重複提交併及時響應 |
內聯查詢 | 跨會話搜索併發送內容 | 快速返回、緩存與結果分頁 |
羣組事件 | 成員、權限和服務消息 | 遵守羣組隱私模式 |
錯誤與重試
區分參數錯誤、權限錯誤、限流、臨時網絡故障和服務端錯誤。只對可恢復問題採用帶抖動的指數退避，並設置最大次數。
不要無限重試：無法送達、權限被撤銷或參數無效時應停止任務並記錄可診斷信息。
安全要求
- 令牌泄露後立即輪換，並排查異常調用。
- 對管理命令、付款或高風險動作進行二次鑑權。
- 僅保存完成服務所需的數據，並制定刪除週期。
- 對用户輸入、URL、文件和富文本進行驗證與過濾。
- 為接口啓用 HTTPS、限流、日誌告警和可用性監控。