跳到主要内容

DeBox 开发者 FAQ / 排障

本页聚焦开发者接入中的高频问题与定位思路。
新接入请先根据 FAQ 1 选择与开发路径对应的主文档。

1. 我应该先看哪篇文档？​

按接入路径选择：

2. 为什么 getUpdates 一直收不到消息？​

最常见原因：已经在 BotMother 中配置了 Webhook URL。

只要 BotMother 中仍有 Webhook URL，getUpdates 就不是有效的收消息路径。如果准备使用 Long Polling，请先清空 Webhook 设置。完整规则和配置流程请查看 收消息模式说明。

3. 消息为什么发错目标或路由校验失败？​

如果消息发错目标或路由参数校验失败，先检查 chat_id 是否与 chat_type 匹配，再对照 OpenAPI 路由规则核对这两个值。

4. 图片或其他媒体消息为什么发送失败？​

完整的 parse_mode 和 content 契约请查看 OpenAPI 消息字段说明。

如果文字消息发送正常，但图片无法发送，请按以下顺序检查：

  1. parse_mode 是否准确填写为 image。
  2. content 是否为可公网访问的图片 URL。
  3. 通过 getMe 检查 result.level，再对照 Bot 等级与图片发送确认当前发送场景的等级要求和管理员例外。
  4. 检查目标聊天是否还受到其他接口、权限、隐私或平台限制。

5. Webhook 鉴权为什么失败？​

将收到的 X-API-KEY 与该 Bot 当前的 Webhook Key 进行比较。如果在 BotMother 中修改了 Webhook Key，Bot 后端用于校验的值也必须同步更新。完整要求请查看 Webhook 请求与校验说明。

6. 发送消息返回失败怎么查？​

OpenAPI 消息字段定义了字段允许值和长度限制。 建议按顺序检查：

  1. 请求头是否带 X-API-KEY。
  2. chat_type/chat_id 是否匹配。
  3. content 是否为空或超限。
  4. parse_mode 与 content 格式是否一致。
  5. 若是签名接口（如 dao_member），检查 nonce/timestamp/signature。

7. 常见错误与处理​

  • message can't be empty：content 为空。
  • message must be less than 5000 characters：文本类消息超长。
  • message must be less than 2000 bytes：粉丝群发内容超限。
  • permission denied：调用方无目标群管理权限。
  • Param error：参数缺失或格式不合法（常见于地址格式）。

8. 找不到目标群的 gid 时怎么获取？​

在 App 内进入目标群，使用“分享/复制链接”，链接中的 id 即 gid。

9. 复制 Bot 凭证后，为什么仍然鉴权失败？​

  • Bot 服务调用 OpenAPI 时，X-API-KEY 必须使用该 Bot 的 App Key（API Key）。签名接口还要 使用同一个 Bot 对应的 App Secret（API Secret）。
  • DeBox 通过 Webhook 调用 Bot 服务时，应使用独立的 Webhook Key 校验收到的 X-API-KEY。

鉴权失败时，先确认请求方向，再检查是否混用了这些值。这三个值都只能保存在可信的后端服务或环境变量中， 不要写入 H5、浏览器端代码、公开仓库、日志或截图。完整的凭证对应关系和配置流程请查看 DeBox 机器人开发总览。

10. BotMother 指令已经显示在菜单里，为什么点击后没有反应？​

BotMother 的指令设置只负责管理 Bot 指令菜单中显示的指令名称和说明。每条指令收到后具体执行什么， 仍然需要在 Bot 后端代码中实现。完整设置流程请查看 DeBox 机器人开发总览。

11. Bot 为什么收不到私信或群消息？​

请以 DeBox 机器人开发总览中的隐私和权限设置为准，再按以下顺序检查：

  1. 在 Bot 隐私设置中，确认私信和群邀请范围包含用于测试的账号。
  2. 先通过私聊测试普通消息和 Bot 需要支持的变体消息。
  3. 未开通“监听群消息”权限时，群内只有明确 @Bot 的普通消息可以投递；不带 @Bot 的普通群消息，以及无论是否明确 @Bot 的群聊变体消息，都需要该权限。完整规则请查看 Bot 消息投递规则。
  4. 如果需要接收上述必须开通权限的群消息，请提交“监听群消息”权限申请并等待平台审核。
  5. 如果申请未通过，可以在 DeBox App 内进入 OpenBOX Bot Release Review 群反馈。

如果符合投递条件的私信或群消息仍然无法收到，还应继续检查 Webhook 与 Long Polling 冲突。

DeBox 内置浏览器只支持 https:// 链接，http:// 链接会被拦截。

链接类型在 DeBox 中的打开结果
http:// 链接被拦截，无法通过内置浏览器打开。
第三方 https:// 链接可以打开，但默认会先显示“第三方网站”安全提示。

是否显示提示取决于链接指向的网页，与链接由谁发送或在聊天中以什么形式出现无关。Bot 发送的文本链接、 按钮和其他消息形式中的链接，普通用户发送的链接，开发者自行开发的 DApp/H5，以及其他第三方网页， 都适用相同规则。将文本链接改成按钮不会消除提示。

如需申请让指定网页或域名打开时不再显示该提示，请联系 DeBox 官方客服进行评估。 是否可以取消提示，以平台审核结果为准。

13. 技术支持渠道​