本文中的 DocOnly、L0–L3 用於說明本指南的測試執行限制與操作風險，不代表介面是否受支援。介面支援狀態應另查官方文件；修改訊息、會話或傳遞設定前，請核對目標和復原方式。
快速解答開發者最先遇到的問題。參數級細節見 core.mp.net/bots。
總覽
按主題分組的常見問題。若這裡沒有你的問題，請查閱本欄目對應指南。
快速開始
從哪開始？使用既有 Bot：查看使用者指南。首次除錯 API：選擇 Windows/macOS 分步教學；熟悉終端機的開發者可選擇 curl 或 Node.js 接入範例，兩條除錯路徑擇一即可。 如何開始使用 Bot：傳送指令與使用聊天按鈕 跑通第一個 MPChat Bot：手機測試與 Windows/macOS 除錯 Bot API 接入範例：用 curl 或 Node.js 收發測試訊息
mpbot 是什麼？測試/開發用 Bot，有獨立 token 與 API 權限，與生產隔離。
token 放哪？環境變數或密鑰管理。絕不進 git、日誌或前端。
收發訊息
Bot 為何不能主動私聊？用戶須先建立上下文；
sendMessage需要有效chat_id。chat_id 如何取得？ 請使用者先傳送訊息給 Bot，再依目前的接收方式，從 Webhook 更新或
getUpdates結果讀取message.chat.id。getUpdates 回傳 []？還沒訊息，或該批已被消費。檢查
offset與 Webhook 狀態。getUpdates 回傳 409？已啟用 Webhook（與輪詢互斥）。用
getWebhookInfo確認；勿自行執行deleteWebhook。
媒體與限制
file_id 能複用嗎？不能。用公網 URL 或 multipart。
banChatMember 會踢人嗎？不會——僅禁言（restricted）。用
unbanChatMember解除。L3 DocOnly。sendPoll / sendLocation 為何不可用？目前回傳 501。
觸發 429 怎麼辦？不超過每秒 30 次，並加指數退避。
MiniApp
前端資料能直接登入嗎？不能。後端必須驗證
initData簽名；initDataUnsafe僅用於 UI。shortName 是 miniapp id 嗎？不是。
shortName是直鏈https://mp.net/{bot}/{shortName}裡的短名；miniapp_id（ma_…）是簽名 initData 裡的平台 ID。如何開啟 MiniApp 指定頁？加
?startapp=…，會進入簽名後的initData.start_param。如何關掉連結預覽卡？ 在
sendMessage中設定link_preview_options.is_disabled=true，可同時關閉一般連結和 MiniApp 連結的預覽卡片。
安全
哪些方法不能隨便測？DocOnly：
logOut、leaveChat、deleteMessage(s)、banChatMember、setWebhook、deleteWebhook。官方參考在哪？core.mp.net/bots——參數級權威來源。
為什麼已有的私聊回傳 HTTP 403？
使用者封鎖 Bot 後，向該私聊傳送、轉傳或複製訊息都會回傳 HTTP 403。收到此錯誤後請跳過重試。解除封鎖後，Bot 可以傳送新訊息。封鎖期間未送達的訊息不會自動補送。
為什麼會重複投遞？待投遞數為 0 代表什麼？
Webhook 重新投遞會沿用原
update_id。驗證請求後，先用 Bot 與update_id組成的唯一鍵持久化更新，再回傳 HTTP 2xx（如 200 或 204）。業務處理也要具備冪等性，避免工作重跑時重複回覆或重複變更狀態。一般更新最多投遞 24 小時。按鈕回呼更新最多投遞 150 秒，
answerCallbackQuery另有 300 秒的回應時限。pending_update_count=0表示目前沒有待投遞的更新。若要確認哪些更新已到達服務，請查看getWebhookInfo的近期投遞錯誤，並核對服務端的接收和處理記錄。
為什麼點回呼按鈕後一直轉圈？
先確認按鈕使用
callback_data。若透過allowed_updates篩選更新類型，應納入callback_query。請檢查服務是否在 150 秒投遞時限內收到該更新。收到後盡快以
callback_query.id呼叫answerCallbackQuery，從點擊產生回呼起 300 秒內完成。同一 ID 僅第一個有效回應成功，重複或逾期回應會回傳 HTTP 400。用戶端不會顯示回應中的
text或show_alert。若要讓使用者看到處理結果，可以編輯訊息或傳送回覆。
為什麼 MiniApp 按鈕在私聊可用，在群組裡卻打不開？
一般
web_app按鈕僅適用於 Bot 私聊。在 Bot 已加入的群組或超級群組分享 MiniApp 時，該則sendMessage的內嵌鍵盤必須恰好一列、一個按鈕，且按鈕只包含text與web_app。也請確認 URL 指向目前 Bot 擁有且已啟用的 MiniApp。
為什麼編輯訊息後按鈕或媒體說明消失了？
複合編輯訊息時，省略內嵌鍵盤或媒體說明對應的欄位，會清除該欄位。若要保留原值，請在編輯請求中一併傳入。若只調整鍵盤或媒體說明，可以使用對應的專用編輯方法。
相關文章
本 FAQ 概括的行為可能變化。請始終在官方方法頁確認當前狀態。