跳到主要内容

DeBox 开发者 OpenAPI

接口清单（按路由顺序）​

  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

能力概览​

能力包含的接口和用途
Bot 与消息获取当前 Bot 信息，发送或编辑消息，向关注者群发，以及接收消息和交互事件。
群组与群管理查询群组和入群状态、查询成员、移出成员，以及撤回群消息。
用户与关系查询用户公开信息和检查关注关系。
Web3 数据查询 Token 基础资料和 BOX 整体信息。

OpenAPI 请求地址（Base URL）​

https://open.debox.pro

鉴权​

需要调用 DeBox OpenAPI 鉴权接口的 DApp，必须先通过 BotMother 创建 Bot。Bot 的 App Key 就是 X-API-KEY 使用的 API Key。该凭证只能保存在后端，不要暴露在 H5 或浏览器端代码中。

除 GET /openapi/box/info 外，均需请求头：

X-API-KEY: <your_api_key>

返回包裹格式​

标准包裹（group/user/token/box）​

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

Bot 包裹（bot 路由）​

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

全局参数值域​

  • chat_type：group | private
  • chat_id：
    • chat_type=group 时：群 gid（如 cc0onr82）
    • chat_type=private 时：填写目标用户的 user_id；该值与目标用户的 uid 和 invite_code 相同，但请求字段仍为 chat_id
  • content：主参数
  • 文本类长度上限（text/richtext/Markdown/MarkdownV2/HTML）：5000 字符
  • parse_mode 默认值：richtext
  • parse_mode 值域：
    • richtext（默认）
    • text
    • Markdown
    • MarkdownV2
    • HTML
    • image
    • video
    • file

content 如何填写（关键）​

  • parse_mode=richtext：填普通文本或富文本字符串（默认），例如 你好，欢迎使用 DeBox Bot。
  • parse_mode=text：填纯文本（不解析 Markdown/HTML），例如 plain text only。
  • parse_mode=Markdown：填 Markdown 内容，例如 **bold**。
  • parse_mode=MarkdownV2：填 MarkdownV2（需要按语法转义），例如 \\*bold\\*。
  • parse_mode=HTML：填 HTML 片段（如 <b>Hello</b>）。
  • parse_mode=image：content 填可公网访问的图片 URL（如 https://cdn.example.com/a.png）。
  • parse_mode=video：content 填可公网访问的视频 URL（如 https://cdn.example.com/a.mp4）。
  • parse_mode=file：content 填可公网访问的文件 URL（如 https://cdn.example.com/a.pdf）。
图片发送的等级要求

发送图片会受到 Bot 等级和目标群管理员身份规则的限制。完整要求、管理员例外、等级检查和升级步骤请查看 Bot 等级与图片发送。

reply_markup / user_action_markup 最小示例​

{
  "inline_keyboard": [
    [
      { "text": "查看详情", "url": "https://docs.debox.pro/ApiOnePage" },
      { "text": "回调按钮", "callback_data": "detail" }
    ]
  ]
}

mention_type / mention_ids 使用建议​

  • 仅 parse_mode=text 时建议使用 mention_type 与 mention_ids。
  • 富文本模式（richtext/Markdown/MarkdownV2/HTML）建议直接在 content 中写 @ 文本，不依赖 mention_* 字段。
  • 若不需要 @ 功能，mention_type 与 mention_ids 可省略。

1. POST /openapi/bot/sendMessage​

通俗说明

  • 需要： App Key、chat_id、chat_type 和消息 content。
  • 可以用于： 回复用户，或者向指定私聊或群聊发送通知。
  • 限制： 每次请求只发送到一个指定私聊或群聊，不是粉丝群发。

Curl 示例​

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"}'

上行参数（Body，JSON）​

  • chat_id string，必填
  • chat_type string，必填，值域：group | private
  • content string，必填
  • parse_mode string，选填，默认 richtext
  • message_id string，选填
  • mention_type int，选填
  • mention_ids string[]，选填
  • reply_markup object，选填
  • user_action_markup object，选填

成功响应示例​

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

失败响应示例​

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

2. POST /openapi/bot/sendMessageToFans​

通俗说明

  • 需要： App Key、已开通的订阅号权限，以及下方参数表列出的消息字段。
  • 可以用于： 向 Bot 关注者批量推送产品更新、服务通知或重要公告。
  • 限制： 消息内容最多为 2000 字节；粉丝范围和投递规则以 Bot 当前获得的平台权限为准。

Curl 示例​

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"}'

上行参数（Body，JSON）​

  • chat_id string，必填
  • chat_type string，必填，值域：group | private
  • content string，必填
  • parse_mode string，选填，默认 richtext

约束：content 最大 2000 字节。

成功响应示例​

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

失败响应示例​

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

3. POST /openapi/bot/editMessage​

通俗说明

  • 需要： App Key、目标聊天、准确的 message_id 和新的消息内容。
  • 可以用于： 修正或更新 Bot 之前发送的消息。
  • 限制： 不能让 Bot 任意编辑其他用户发送的消息。

Curl 示例​

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"}'

上行参数（Body，JSON）​

  • chat_id string，必填
  • chat_type string，必填，值域：group | private
  • message_id string，必填
  • content string，必填
  • parse_mode string，选填，默认 richtext

成功响应示例​

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

失败响应示例​

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

4. POST /openapi/bot/getMe​

通俗说明

  • 需要： App Key，不需要请求 Body。
  • 可以用于： 检查当前 Bot 的 ID、资料、地址和等级。
  • 限制： 只返回当前 App Key 绑定的 Bot，不用于查询普通用户资料。

Curl 示例​

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

上行参数​

无。

成功响应示例​

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

失败响应示例​

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

5. POST /openapi/bot/getUpdates​

通俗说明

  • 需要： App Key，并将 Long Polling 作为当前收消息方式。
  • 可以用于： 接收发送给 Bot 的新消息和交互事件。
  • 限制： Webhook 与 Long Polling 二选一，而且该接口不是通用的历史聊天记录查询接口。

Curl 示例​

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}'

如果 BotMother 中配置了 Webhook URL，Webhook 是唯一有效的收消息链路，本接口不能用于收消息。使用 getUpdates 进行 Long Polling 前，必须先清空 Webhook 配置。

上行参数（Body，JSON）​

  • timeout int，选填，值域 1~60，默认 30

成功响应示例（有消息）​

{
  "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"
      }
    }
  ]
}

成功响应示例（超时无消息）​

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

失败响应示例​

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

6. GET /openapi/group/info​

通俗说明

  • 需要： App Key 和群组 gid。
  • 可以用于： 确认群 ID 是否正确，或者在发送通知、执行群操作前展示群组基本信息。
  • 限制： 只返回群组基本资料，不返回完整成员列表；如需成员列表，应使用 dao_member。

Curl 示例​

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

Query 参数​

  • gid string，必填

成功响应示例​

{
  "code": 200,
  "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": "无限制",
    "mod": ["Alice", "Bob"],
    "mod_info": [
      {
        "name": "Alice",
        "address": "0x...",
        "pic": "https://...",
        "user_id": "u1"
      }
    ]
  }
}

失败响应示例​

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

7. GET /openapi/group/is_join​

通俗说明

  • 需要： App Key、群组 gid 和 EVM 钱包地址 walletAddress。
  • 可以用于： 校验指定钱包地址是否已加入目标群，例如用于群成员专属功能的访问控制或奖励资格判断。
  • 限制： 只返回是否入群的布尔结果，不会执行加群，也不会返回成员列表。

Curl 示例​

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

Query 参数​

  • gid string，必填
  • walletAddress string，必填，EVM 地址

成功响应示例​

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

失败响应示例​

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

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

通俗说明

  • 需要： App Key、签名请求头、群组 gid，以及 Bot 在该群所需的管理权限。
  • 可以用于： 分页读取当前群成员列表和成员公开资料。
  • 限制： 每页最多返回 50 位成员；不会返回历史聊天消息或成员私聊内容。

Curl 示例​

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}'

额外请求头（必填）​

  • nonce string
  • timestamp string
  • signature string

签名算法：sha1(app_secret + nonce + timestamp)。

上行参数（Body，JSON）​

  • gid string，必填，长度 1~8
  • page int，选填，<=0 时按 1
  • size int，选填，默认 50，最大 50

成功响应示例​

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

失败响应示例​

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

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

通俗说明

  • 需要： App Key、签名请求头、目标群 gid、成员 user_id，以及管理员或建群者权限。
  • 可以用于： 根据群管理规则将指定成员移出目标群，例如处理广告骚扰、违规行为，或成员不再符合群准入条件的情况。
  • 限制： 该操作会改变群状态，每次最多处理 20 位用户；首次使用时应先通过测试账号验证。

接口说明​

将一个或多个成员移出指定 DeBox 群组。

该接口要求当前 X-API-KEY 绑定的 Bot 已加入目标群组，且在该群内具备管理员或建群者权限。

Curl 示例​

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"]
  }'

额外请求头（必填）​

  • nonce string
  • timestamp string
  • signature string

签名算法：sha1(app_secret + nonce + timestamp)。

权限要求​

  • X-API-KEY 必须合法有效。
  • API Key 必须已绑定一个有效的 DeBox Bot 账号。
  • 该 Bot 必须在目标群组中具备管理员或建群者权限。

上行参数（Body，JSON）​

  • gid string，必填，目标群组 ID，长度 1~8
  • user_ids string[]，必填，待移出成员的 DeBox user_id 列表
  • user_ids 单次最多传入 20 个成员

参数校验与执行规则​

  • user_ids 不能为空数组。
  • user_ids 中不允许出现空字符串。
  • 重复的 user_id 会在服务端自动去重后再执行。
  • 只要请求中的任意一个 user_id 无法解析为有效用户，接口会直接失败。

成功响应示例​

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

失败响应示例​

{
  "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​

通俗说明

  • 需要： App Key、签名请求头、管理员或建群者权限、群组 gid、原发送者 user_id 和准确的 message_id。
  • 可以用于： 根据群管理规则撤回目标群中的指定消息，例如处理广告骚扰、违规内容或误发消息。
  • 限制： 消息和发送者必须与目标群匹配；该接口不是历史消息搜索或任意消息删除接口。

接口说明​

管理员撤回群消息接口。

消息撤回后，将展示为如下群通知内容：

MOD {operator_name} 撤回了 {sender_name}的消息

Curl 示例​

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"
  }'

额外请求头（必填）​

  • nonce string
  • timestamp string
  • signature string

签名算法：sha1(app_secret + nonce + timestamp)。

权限要求​

  • X-API-KEY 必须合法有效。
  • API Key 必须已绑定一个有效的 DeBox Bot 账号。
  • 该 Bot 必须在目标群组中具备管理员或建群者权限。

上行参数（Body，JSON）​

  • gid string，必填，目标群组 ID，长度 1~8
  • user_id string，必填，原消息发送者的 DeBox user_id
  • message_id string，必填，待撤回消息的消息 ID

注意事项​

  • user_id 必须能解析到一个真实存在的 DeBox 用户。
  • message_id 必须对应目标群组内一条可被平台修改的消息。
  • 撤回通知中的操作者名称，优先取管理员 Bot 的展示名；若展示名为空，则回退为其 user_id。
  • 原消息发送者名称同样优先取展示名，缺失时回退为其 user_id。

成功响应示例​

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

失败响应示例​

{
  "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​

通俗说明

  • 需要： App Key，以及 DeBox user_id 或 EVM 钱包地址，两者至少提供一个。
  • 可以用于： 展示用户公开昵称和头像，或者根据钱包地址查找对应的 DeBox 公开资料。
  • 限制： 只返回公开资料字段，不涉及私聊、历史消息或私钥。

Curl 示例​

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

Query 参数​

  • user_id string，选填
  • address string，选填，EVM 地址
  • 至少一个必填

成功响应示例​

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

失败响应示例​

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

12. GET /openapi/user/is_follow​

通俗说明

  • 需要： App Key、walletAddress 和 followAddress。
  • 可以用于： 校验指定钱包地址对应的账号是否已关注目标账号，例如用于关注者专属功能的访问控制或奖励资格判断。
  • 限制： 结果有明确方向且只返回布尔值，不会代替用户执行关注操作。

Curl 示例​

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

Query 参数​

  • walletAddress string，必填，EVM 地址
  • followAddress string，必填，EVM 地址

成功响应示例​

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

失败响应示例​

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

13. GET /openapi/token/info​

通俗说明

  • 需要： App Key 和 contract_address；chain_id 选填，缺失或为负值时按 0 处理。
  • 可以用于： 用户输入合约地址后，展示 Token 名称、符号、精度和 Logo。
  • 限制： 只返回 Token 基础资料，不返回市场价格或某个钱包的代币余额。

Curl 示例​

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

Query 参数​

  • contract_address string，必填
  • chain_id int，选填；缺失/负值按 0

成功响应示例​

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

失败响应示例​

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

14. GET /openapi/box/info​

通俗说明

  • 需要： 不需要参数，也不需要 App Key。
  • 可以用于： 查询 BOX 的全局数据，例如最大供应量、当前供应量、销毁量和锁定量。
  • 限制： 返回的是 BOX 整体数据，不是某个用户持有的 BOX 数量。

Curl 示例​

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

Query 参数​

无。

成功响应示例​

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