跳到主要内容

DeBox 机器人 Nodejs SDK 使用文档

源码仓库：

1. SDK 功能总览​

debox-chat-nodejs-sdk 提供：

  • Bot 初始化：NewBotAPI(apiKey, apiSecret)
  • 消息发送：bot.Send(...)
  • Long Polling 收消息：GetUpdates / GetUpdatesChan
  • 按钮与回调处理
  • 编辑消息：NewEditMessageText(...) / NewEditMessageTextAndMarkup(...)

2. 收消息模式说明​

本文使用 Long Polling。运行前必须清空 BotMother 中已经配置的 Webhook URL，否则 Long Polling 不能用于收消息。模式选择和切换方法请查看DeBox 机器人开发总览，Webhook 实现请查看DeBox 机器人 Go SDK Webhook。

3. 安装与初始化​

3.1 安装 SDK​

npm install github:debox-pro/debox-chat-nodejs-sdk

或本地拉取安装：

git clone https://github.com/debox-pro/debox-chat-nodejs-sdk.git
cd debox-chat-nodejs-sdk
npm install

3.2 准备凭证​

BotMother 的 Bot 详情页显示 App Key 和 App Secret，在 SDK 中按以下关系使用：

  • App Key → API_KEY（必须）
  • App Secret → API_SECRET（建议）

完整对应关系和保存要求请查看DeBox 机器人开发总览中的凭证说明。

环境变量示例：

export DEBOX_BOT_API_KEY="YOUR_APP_KEY"
export DEBOX_BOT_API_SECRET="YOUR_API_SECRET"

3.3 发送第一条消息​

const boxbotapi = require("./boxbotapi");

async function main() {
  const bot = await boxbotapi.NewBotAPI(
    process.env.DEBOX_BOT_API_KEY,
    process.env.DEBOX_BOT_API_SECRET || "",
  );

  const msg = boxbotapi.NewMessage("cc0onr82", "group", "Hello from Nodejs SDK");
  msg.ParseMode = boxbotapi.ModeRichText;

  const sent = await bot.Send(msg);
  console.log("sent message_id=", sent.MessageID);
}

main().catch(console.error);

4. Long Polling 收消息​

const boxbotapi = require("./boxbotapi");

async function run() {
  boxbotapi.Debug = false;
  boxbotapi.MessageListener = true;

  const bot = await boxbotapi.NewBotAPI(
    process.env.DEBOX_BOT_API_KEY,
    process.env.DEBOX_BOT_API_SECRET || "",
  );

  const u = boxbotapi.NewUpdate(0);
  u.Timeout = 60;

  for await (const update of bot.GetUpdatesChan(u)) {
    if (update.Message) {
      const text = update.Message.Text || "";
      console.log("message:", text);

      const reply = boxbotapi.NewMessage(
        update.Message.Chat.ID,
        update.Message.Chat.Type,
        `Received: ${text}`,
      );
      reply.ParseMode = boxbotapi.ModeRichText;
      await bot.Send(reply);
    }

    if (update.CallbackQuery) {
      console.log("callback:", update.CallbackQuery.Data);
    }
  }
}

run().catch(console.error);

5. ParseMode 常量​

SDK 常量：

  • boxbotapi.ModeRichText
  • boxbotapi.ModeMarkdown
  • boxbotapi.ModeMarkdownV2
  • boxbotapi.ModeHTML
  • boxbotapi.ModeImage
  • boxbotapi.ModeVideo
  • boxbotapi.ModeFile

parse_mode、content、媒体 URL 和长度规则请查看 OpenAPI 消息字段说明。

6. 按钮与回调​

const markup = boxbotapi.NewInlineKeyboardMarkup(
  boxbotapi.NewInlineKeyboardRow(
    boxbotapi.NewInlineKeyboardButtonData("查看详情", "detail"),
    boxbotapi.NewInlineKeyboardButtonURL("打开文档", "https://docs.debox.pro"),
  ),
);

const msg = boxbotapi.NewMessage("cc0onr82", "group", "请选择");
msg.ParseMode = boxbotapi.ModeRichText;
msg.ReplyMarkup = markup;
await bot.Send(msg);

处理回调并编辑消息：

if (update.CallbackQuery) {
  const data = update.CallbackQuery.Data;
  const chat = update.CallbackQuery.Message.Chat;
  const messageId = update.CallbackQuery.Message.MessageID;

  const edit = boxbotapi.NewEditMessageText(chat.ID, chat.Type, messageId, `clicked: ${data}`);
  edit.ParseMode = boxbotapi.ModeRichText;
  await bot.Send(edit);
}

7. 路由字段说明​

请按照 OpenAPI 路由规则向 SDK 构造函数传入 chat_id 和 chat_type。

8. 常见问题​

  1. 收不到消息：
  • 先检查是否已配置 webhook（与轮询互斥）。
  • 确保 boxbotapi.MessageListener = true。
  1. 鉴权失败：
  • 检查 API_KEY/API_SECRET 是否正确。
  1. 媒体发送失败：