跳到主要内容

DeBox 机器人 Nodejs SDK 使用文档

源码仓库：

1. SDK 功能总览​

debox-chat-nodejs-sdk 提供：

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

2. 收消息模式说明​

本文聚焦 Long Polling 模式。

Webhook 与 Long Polling 严格互斥：

  • 开放平台配置了 webhook 后，消息只会进入 webhook。
  • 要使用轮询收消息，先清空 webhook 配置。

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 准备凭证​

从 DeBox 开放平台获取：

  • API_KEY（必填）
  • API_SECRET（建议）

环境变量示例：

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 与 content 规则​

SDK 常量：

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

content 填写规则：

  • richtext / Markdown / MarkdownV2 / HTML：填写文本内容。
  • image / video / file：content 必须为公网可访问 URL。
  • 文本内容最大长度 5000 字符。

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. 路由字段说明​

发送/编辑消息时：

  • chat_type=group -> chat_id 填群 gid
  • chat_type=private -> chat_id 填用户 user_id（invite code）

8. 常见问题​

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