Skip to main content

DeBox Developer OpenAPI

Endpoint Index (Ordered)​

  1. POST /openapi/bot/sendMessage
  2. POST /openapi/bot/sendMessageToFans
  3. POST /openapi/bot/editMessage
  4. POST /openapi/bot/getMe
  5. POST /openapi/bot/getUpdates
  6. GET /openapi/group/info
  7. GET /openapi/group/is_join
  8. POST /openapi/group/admin/dao_member
  9. POST /openapi/group/admin/kick_member
  10. POST /openapi/group/admin/message/recall
  11. GET /openapi/user/info
  12. GET /openapi/user/is_follow
  13. GET /openapi/token/info
  14. GET /openapi/box/info

Capability Overview​

CapabilityEndpoints and uses
Bot and messagingGet the current bot, send or edit messages, broadcast to followers, and receive messages and interaction events.
Groups and moderationQuery groups and membership, list members, remove members, and recall group messages.
Users and relationshipsQuery public user information and check follow relationships.
Web3 dataQuery token metadata and overall BOX information.

OpenAPI request address (Base URL)​

https://open.debox.pro

Authentication​

A DApp that needs authenticated DeBox OpenAPI endpoints must first create a bot through BotMother. The bot's App Key is the API Key used in X-API-KEY. Keep it on the backend and never expose it in H5 or browser code.

All endpoints except GET /openapi/box/info require:

X-API-KEY: <your_api_key>

Response Envelopes​

Standard envelope​

{
  "code": 1,
  "success": true,
  "data": {}
}

Bot envelope​

{
  "ok": true,
  "success": true,
  "result": {}
}

Global Parameter Ranges​

  • chat_type: group | private
  • chat_id:
    • when chat_type=group: group gid
    • when chat_type=private: target user's user_id; this value is the same as that user's uid and invite_code, but the request field remains chat_id
  • content is the primary field
  • max length for text-like modes (text/richtext/Markdown/MarkdownV2/HTML): 5000 chars
  • default parse_mode: richtext
  • parse_mode enum:
    • richtext (default)
    • text
    • Markdown
    • MarkdownV2
    • HTML
    • image
    • video
    • file

How to fill content (critical)​

  • parse_mode=richtext: normal text/rich text string (default), e.g. Hello, welcome to DeBox Bot.
  • parse_mode=text: plain text only (no Markdown/HTML parsing), e.g. plain text only.
  • parse_mode=Markdown: Markdown content, e.g. **bold**.
  • parse_mode=MarkdownV2: MarkdownV2 content (escape special chars as required), e.g. \\*bold\\*.
  • parse_mode=HTML: HTML fragment (e.g. <b>Hello</b>).
  • parse_mode=image: set content to a public image URL (e.g. https://cdn.example.com/a.png).
  • parse_mode=video: set content to a public video URL (e.g. https://cdn.example.com/a.mp4).
  • parse_mode=file: set content to a public file URL (e.g. https://cdn.example.com/a.pdf).
Image-sending level requirement

Image sending is subject to bot-level and target-group administrator rules. See Bot level and image sending for the complete requirements, administrator exception, level check, and upgrade steps.

Minimal reply_markup / user_action_markup sample​

{
  "inline_keyboard": [
    [
      { "text": "View detail", "url": "https://docs.debox.pro/en/ApiOnePage" },
      { "text": "Callback button", "callback_data": "detail" }
    ]
  ]
}

mention_type / mention_ids practical guidance​

  • Recommended mainly when parse_mode=text.
  • For rich text modes (richtext/Markdown/MarkdownV2/HTML), prefer writing @ directly in content and avoid mention_*.
  • If no mention behavior is needed, omit both fields.

1. POST /openapi/bot/sendMessage​

At a glance

  • Requires: an App Key, chat_id, chat_type, and message content.
  • Useful for: replying to a user or sending a notification to a specified private chat or group.
  • Limits: each request sends to one specified private chat or group; it is not a fan broadcast.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/bot/sendMessage" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -d '{"chat_id":"cc0onr82","chat_type":"group","content":"hello","parse_mode":"richtext"}'

Request params (Body, JSON)​

  • chat_id string, required
  • chat_type string, required, enum: group | private
  • content string, required
  • parse_mode string, optional, default richtext
  • message_id string, optional
  • mention_type int, optional
  • mention_ids string[], optional
  • reply_markup object, optional
  • user_action_markup object, optional

Success response example​

{
  "ok": true,
  "success": true,
  "result": {
    "message_id": "01JYXXXX",
    "text": "Hello from DeBox",
    "parse_mode": "richtext"
  }
}

Error response example​

{
  "ok": false,
  "success": false,
  "message": "message can't be empty"
}

2. POST /openapi/bot/sendMessageToFans​

At a glance

  • Requires: an App Key, approved subscription-account permission, and the message fields listed below.
  • Useful for: broadcasting product updates, service notices, or announcements to the bot's followers.
  • Limits: content is limited to 2000 bytes; follower scope and delivery rules follow the bot's current platform permissions.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/bot/sendMessageToFans" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -d '{"chat_id":"cc0onr82","chat_type":"group","content":"broadcast","parse_mode":"richtext"}'

Request params (Body, JSON)​

  • chat_id string, required
  • chat_type string, required, enum: group | private
  • content string, required
  • parse_mode string, optional, default richtext

Constraint: content max 2000 bytes.

Success response example​

{
  "ok": true,
  "success": true,
  "result": true
}

Error response example​

{
  "ok": false,
  "success": false,
  "message": "message must be less than 2000 bytes"
}

3. POST /openapi/bot/editMessage​

At a glance

  • Requires: an App Key, the target chat, the exact message_id, and the replacement content.
  • Useful for: correcting or updating a message previously sent by the bot.
  • Limits: it does not allow the bot to edit arbitrary messages sent by other users.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/bot/editMessage" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -d '{"chat_id":"cc0onr82","chat_type":"group","message_id":"01JYXXXX","content":"edited","parse_mode":"richtext"}'

Request params (Body, JSON)​

  • chat_id string, required
  • chat_type string, required, enum: group | private
  • message_id string, required
  • content string, required
  • parse_mode string, optional, default richtext

Success response example​

{
  "ok": true,
  "success": true,
  "result": true
}

Error response example​

{
  "ok": false,
  "success": false,
  "message": "EditMessageText param Group Id is error"
}

4. POST /openapi/bot/getMe​

At a glance

  • Requires: an App Key; no request body is required.
  • Useful for: checking the current bot's ID, profile, address, and level.
  • Limits: it returns the bot bound to the current App Key, not an ordinary user's profile.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/bot/getMe" \
  -H "X-API-KEY: YOUR_APP_KEY"

Request params​

None.

Success response example​

{
  "ok": true,
  "success": true,
  "result": {
    "name": "DeBox Bot",
    "address": "0x...",
    "pic": "https://...",
    "user_id": "u1",
    "level": 3,
    "level_icon": "https://.../icon/level/v3.png"
  }
}

Error response example​

{
  "ok": false,
  "success": false,
  "message": "invalid param"
}

5. POST /openapi/bot/getUpdates​

At a glance

  • Requires: an App Key and Long Polling as the active receiving mode.
  • Useful for: receiving new messages and interaction events sent to the bot.
  • Limits: Webhook and Long Polling are mutually exclusive, and this endpoint is not a general chat-history query.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/bot/getUpdates" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -d '{"timeout":30}'

Request params (Body, JSON)​

  • timeout int, optional, range 1~60, default 30

If a Webhook URL is configured in BotMother, Webhook is the only effective receiving path and this endpoint cannot be used to receive messages. Clear the Webhook settings before using getUpdates for Long Polling.

Success response example (with updates)​

{
  "ok": true,
  "success": true,
  "result": [
    {
      "id": 123,
      "message": {
        "message_id": "01JYXXXX",
        "from": {
          "user_id": "u1",
          "name": "Alice",
          "address": "0x..."
        },
        "chat": {
          "id": "cc0onr82",
          "type": "group"
        },
        "text": "Ping",
        "parse_mode": "richtext"
      }
    }
  ]
}

Success response example (timeout, no updates)​

{
  "ok": true,
  "success": true,
  "result": []
}

Error response example​

{
  "ok": false,
  "success": false,
  "message": "Invalid timeout value"
}

6. GET /openapi/group/info​

At a glance

  • Requires: an App Key and the group gid.
  • Useful for: validating a group ID and displaying basic group information before sending notifications or performing group operations.
  • Limits: it returns group metadata, not the complete member list; use dao_member when a member list is required.

Curl Example​

curl "https://open.debox.pro/openapi/group/info?gid=cc0onr82" \
  -H "X-API-KEY: YOUR_APP_KEY"

Query params​

  • gid string, required

Success response example​

{
  "code": 1,
  "success": true,
  "data": {
    "is_charge": false,
    "subchannel_number": 2,
    "group_name": "DeBox Dev",
    "gid": "cc0onr82",
    "group_number": 345,
    "group_pic": "https://...",
    "create_time": "2026-05-14 14:00:00",
    "maximum": "Unlimited",
    "mod": ["Alice", "Bob"],
    "mod_info": [
      {
        "name": "Alice",
        "address": "0x...",
        "pic": "https://...",
        "user_id": "u1"
      }
    ]
  }
}

Error response example​

{
  "code": -3001,
  "success": false,
  "message": "No such group"
}

7. GET /openapi/group/is_join​

At a glance

  • Requires: an App Key, the group gid, and an EVM walletAddress.
  • Useful for: checking membership before opening member-only features or issuing rewards.
  • Limits: it only returns a Boolean membership result; it does not join the user to the group or return the member list.

Curl Example​

curl "https://open.debox.pro/openapi/group/is_join?gid=cc0onr82&walletAddress=0x1234567890abcdef1234567890abcdef12345678" \
  -H "X-API-KEY: YOUR_APP_KEY"

Query params​

  • gid string, required
  • walletAddress string, required (EVM address)

Success response example​

{
  "code": 1,
  "data": true
}

Error response example​

{
  "error": "Bad Request",
  "code": 401,
  "message": "Param error"
}

8. POST /openapi/group/admin/dao_member​

At a glance

  • Requires: an App Key, signed request headers, the group gid, and the required management permission in that group.
  • Useful for: reading the current member list and public member profiles page by page.
  • Limits: each page contains at most 50 members; the endpoint does not return historical chat messages or private conversations.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/group/admin/dao_member" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -H "nonce: RANDOM_NONCE" \
  -H "timestamp: 1715500000" \
  -H "signature: SHA1(app_secret+nonce+timestamp)" \
  -d '{"gid":"cc0onr82","page":1,"size":20}'

Extra headers (required)​

  • nonce string
  • timestamp string
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Request params (Body, JSON)​

  • gid string, required, length 1~8
  • page int, optional, if <=0 then treated as 1
  • size int, optional, default 50, max 50

Success response example​

{
  "code": 1,
  "success": true,
  "data": [
    {
      "user_id": "u1",
      "name": "Alice",
      "pic": "https://...",
      "address": "0x...",
      "signature": "builder"
    }
  ]
}

Error response example​

{
  "code": -4017,
  "success": false,
  "message": "permission denied"
}

9. POST /openapi/group/admin/kick_member​

At a glance

  • Requires: an App Key, signed request headers, the target gid, member user_id values, and moderator or builder permission.
  • Useful for: removing spam accounts, invalid members, or users who no longer meet a group's access rules.
  • Limits: this operation changes group state and accepts at most 20 users per request; verify it with test accounts first.

Purpose​

Remove one or more members from a DeBox group.

The bot account bound to the current X-API-KEY must already be in the target group and must have moderator or builder permission in that group.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/group/admin/kick_member" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -H "nonce: RANDOM_NONCE" \
  -H "timestamp: 1715500000" \
  -H "signature: SHA1(app_secret+nonce+timestamp)" \
  -d '{
    "gid":"cc0onr82",
    "user_ids":["u1","u2"]
  }'

Extra headers (required)​

  • nonce string
  • timestamp string
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Permission requirements​

  • X-API-KEY must be valid.
  • The API key must be bound to an existing DeBox bot account.
  • The bound bot must be a moderator or builder of the target group.

Request params (Body, JSON)​

  • gid string, required, target group ID, length 1~8
  • user_ids string array, required, list of DeBox user_id values to remove
  • user_ids maximum size: 20 per request

Validation and execution rules​

  • Empty user_ids is rejected.
  • Empty string items inside user_ids are rejected.
  • Duplicate user_id values are de-duplicated before execution.
  • If any provided user_id cannot be resolved to a valid user, the request fails.

Success response example​

{
  "code": 1,
  "success": true,
  "message": "success",
  "data": true
}

Error response examples​

{
  "code": -2004,
  "success": false,
  "message": "uid size must be less than or equal to 20",
  "data": null
}
{
  "code": -4017,
  "success": false,
  "message": "permission denied",
  "data": null
}

10. POST /openapi/group/admin/message/recall​

At a glance

  • Requires: an App Key, signed request headers, moderator or builder permission, the group gid, the original sender's user_id, and the exact message_id.
  • Useful for: recalling a specific spam, policy-violating, or incorrectly sent group message.
  • Limits: the message and sender must match the target group; this is not a general history search or arbitrary message deletion API.

Purpose​

Recall a group message through an administrator action.

After a successful recall, the group displays a system notification similar to:

MOD {operator_name} recalled {sender_name}'s message.

The exact wording follows the language selected in the DeBox App.

Curl Example​

curl -X POST "https://open.debox.pro/openapi/group/admin/message/recall" \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_APP_KEY" \
  -H "nonce: RANDOM_NONCE" \
  -H "timestamp: 1715500000" \
  -H "signature: SHA1(app_secret+nonce+timestamp)" \
  -d '{
    "gid":"cc0onr82",
    "user_id":"u1",
    "message_id":"01HXYZABCDEF1234567890"
  }'

Extra headers (required)​

  • nonce string
  • timestamp string
  • signature string

Signature algorithm: sha1(app_secret + nonce + timestamp).

Permission requirements​

  • X-API-KEY must be valid.
  • The API key must be bound to an existing DeBox bot account.
  • The bound bot must be a moderator or builder of the target group.

Request params (Body, JSON)​

  • gid string, required, target group ID, length 1~8
  • user_id string, required, DeBox user_id of the original sender
  • message_id string, required, message ID to recall

Important notes​

  • user_id must resolve to an existing DeBox user.
  • message_id must identify a message in the target group that can be modified by the platform.
  • The operator name in the recall notice prefers the bot display name and falls back to the bot user_id.
  • The original sender name follows the same fallback rule.

Success response example​

{
  "code": 1,
  "success": true,
  "message": "success",
  "data": true
}

Error response examples​

{
  "code": -2004,
  "success": false,
  "message": "message_id is required",
  "data": null
}
{
  "code": -2000,
  "success": false,
  "message": "recall message failed",
  "data": null
}

11. GET /openapi/user/info​

At a glance

  • Requires: an App Key and either a DeBox user_id or an EVM wallet address.
  • Useful for: displaying a user's public name and avatar or matching a wallet address to a DeBox profile.
  • Limits: it returns public profile fields, not private chats, message history, or private keys.

Curl Example​

curl "https://open.debox.pro/openapi/user/info?user_id=u1" \
  -H "X-API-KEY: YOUR_APP_KEY"

Query params​

  • user_id string, optional
  • address string, optional (EVM address)
  • at least one is required

Success response example​

{
  "code": 1,
  "success": true,
  "data": {
    "user_id": "u1",
    "name": "Alice",
    "address": "0x...",
    "pic": "https://...",
    "signature": "gm builder"
  }
}

Error response example​

{
  "code": -2004,
  "success": false,
  "message": "invalid param"
}

12. GET /openapi/user/is_follow​

At a glance

  • Requires: an App Key, walletAddress, and followAddress.
  • Useful for: checking whether one account follows another before enabling follower-only features or rewards.
  • Limits: the result is directional and Boolean; the endpoint does not perform a follow action for the user.

Curl Example​

curl "https://open.debox.pro/openapi/user/is_follow?walletAddress=0x1234567890abcdef1234567890abcdef12345678&followAddress=0xabcdefabcdefabcdefabcdefabcdefabcdefabcd" \
  -H "X-API-KEY: YOUR_APP_KEY"

Query params​

  • walletAddress string, required (EVM address)
  • followAddress string, required (EVM address)

Success response example​

{
  "code": 1,
  "data": true
}

Error response example​

{
  "error": "Bad Request",
  "code": 401,
  "message": "Please input the wallet address correctly"
}

13. GET /openapi/token/info​

At a glance

  • Requires: an App Key and contract_address; chain_id is optional and is treated as 0 when omitted or negative.
  • Useful for: displaying a token's name, symbol, decimals, and logo after a contract address is entered.
  • Limits: it returns token metadata, not market price or the token balance of a wallet.

Curl Example​

curl "https://open.debox.pro/openapi/token/info?contract_address=0x55d398326f99059fF775485246999027B3197955&chain_id=56" \
  -H "X-API-KEY: YOUR_APP_KEY"

Query params​

  • contract_address string, required
  • chain_id int, optional; missing/negative is treated as 0

Success response example​

{
  "code": 1,
  "success": true,
  "data": {
    "chain_id": 56,
    "token": "0x55d398326f99059fF775485246999027B3197955",
    "decimal": 18,
    "name": "Tether USD",
    "symbol": "USDT",
    "logo_url": "https://..."
  }
}

Error response example​

{
  "code": -2004,
  "success": false,
  "message": "contract_address must be a valid contract address"
}

14. GET /openapi/box/info​

At a glance

  • Requires: no parameters and no App Key.
  • Useful for: displaying overall BOX information in dashboards or statistics pages.
  • Limits: it returns overall BOX data, not the BOX balance held by a specific user.

Curl Example​

curl "https://open.debox.pro/openapi/box/info"

Public endpoint, no API key required.

Query params​

None.

Success response example​

{
  "code": 1,
  "success": true,
  "data": {
    "max_supply": "1000000000",
    "burned": "...",
    "supply": "...",
    "locked": "...",
    "address": "0x...",
    "symbol": "BOX",
    "chainId": 1,
    "icon": "https://...",
    "stake": "..."
  }
}