跳转到主要内容

Bot 与 MiniApp 开发常见问题

MPChat Bot 与 MiniApp 最常见问题的快速解答：如何拿 chat_id、处理 409、file_id 复用、429 应对、initData 能否登录、哪些方法不能随便测。

本文中的 DocOnly、L0–L3 用于说明本指南的测试执行约束与操作风险，不代表接口是否受支持。接口支持状态应另查官方文档；修改消息、会话或投递配置前，请核对目标和恢复方式。

快速解答开发者最先遇到的问题。参数级细节见 core.mp.net/bots。

总览

按话题分组的常见问题。若这里没有你的问题，请查阅本栏目对应指南。

快速开始

收发消息

  • 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 概括的行为可能变化。请始终在官方方法页确认当前状态。

相关文章
这是否解答了您的问题？