Skip to main content

DeBox Developer FAQ / Troubleshooting

This page covers high-frequency integration issues and practical diagnosis paths.
For a new integration, start with the primary document that matches your path in FAQ 1.

1. Which document should I start with?​

Choose by integration path:

2. Why does getUpdates return no messages?​

Most likely a webhook is already configured in BotMother.

If BotMother still has a Webhook URL, getUpdates is not an active receiving path. If you intend to use Long Polling, clear the Webhook settings first. See the receiving-mode setup for the complete rule and configuration flow.

3. Why does a message reach the wrong target or fail routing validation?​

If a message reaches the wrong target or routing validation fails, check that chat_id matches chat_type, then compare both values with the OpenAPI routing rules.

4. Why does an image or other media message fail to send?​

The complete parse_mode and content contract is in the OpenAPI message fields.

If text messages work but an image does not send, check in this order:

  1. parse_mode is exactly image.
  2. content is a publicly accessible image URL.
  3. Use getMe to check result.level, then compare the destination with the requirements and administrator exception in Bot level and image sending.
  4. Check any remaining API, permission, privacy, or platform restrictions for the target chat.

5. Why does webhook authentication fail?​

Compare the incoming X-API-KEY with the bot's current Webhook Key. If the key was changed in BotMother, update the value used by the backend validator at the same time. See the Webhook request and validation contract for the complete requirements.

6. How to diagnose send failures?​

The OpenAPI message fields define the allowed values and limits. Recommended check order:

  1. X-API-KEY header exists and is valid.
  2. chat_type/chat_id mapping is correct.
  3. content is not empty and within limits.
  4. parse_mode matches content format.
  5. For signed endpoints (such as dao_member), verify nonce/timestamp/signature.

7. Common errors and fixes​

  • message can't be empty: missing content.
  • message must be less than 5000 characters: text-mode payload too long.
  • message must be less than 2000 bytes: fan-broadcast payload too large.
  • permission denied: caller has no required group admin permission.
  • Param error: missing/invalid parameters (often malformed addresses).

8. Why can't I find the target group's gid?​

Open the target group in app and copy its share link. The id query value is gid.

9. Why does authentication fail after I copy the bot credentials?​

  • When the bot service calls OpenAPI, X-API-KEY must use the bot's App Key (API Key). Signed endpoints also require the matching App Secret (API Secret) from the same bot.
  • When DeBox calls the bot service through Webhook, validate the incoming X-API-KEY with the separate Webhook Key.

If authentication fails, first check the request direction and make sure these values were not mixed. Keep all three values in a trusted backend or environment variables. Do not put them in H5 pages, browser code, public repositories, logs, or screenshots. See DeBox Bot Development Overview for the complete credential mapping and setup flow.

10. Why does a BotMother command appear in the menu but do nothing?​

BotMother command settings only control the command names and descriptions shown in the bot's command menu. The bot service must still implement the message handling and business behavior for each command. See DeBox Bot Development Overview for the complete setup flow.

11. Why does the bot not receive private or group messages?​

Use the privacy and permission settings in DeBox Bot Development Overview as the primary reference, then check these layers:

  1. In the bot privacy settings, make sure the direct-message and group-invitation scopes include the account used for testing.
  2. Complete the initial message flow in a private chat first.
  3. Before group-message permission is approved, explicitly @Bot in the group; messages that mention the bot are delivered.
  4. Receiving ordinary group messages without an @ mention requires the Listen to Group Messages permission and platform approval.
  5. If the application is not approved, request feedback in the OpenBOX Bot Release Review group in the DeBox App.

If neither private messages nor group mentions arrive, also check the Webhook and Long Polling conflict.

The DeBox in-app browser supports only https:// URLs. It blocks http:// URLs.

URLResult in DeBox
http:// URLBlocked and cannot be opened in the in-app browser.
Third-party https:// URLCan be opened, but shows a third-party website security notice by default.

The warning depends on the destination, not on who sent the link or how it appears in the chat. The same rule applies to links in bot text messages, bot buttons and other message formats, links sent by ordinary users, developer-built DApps/H5 pages, and other external websites. Changing a text link to a button does not remove the warning.

To request an assessment for opening a specific website or domain without the warning, contact DeBox official support. Whether the warning can be removed is subject to platform review.

13. Support channels​