Skip to main content

DeBox Bot Nodejs SDK Guide

Source repository:

1. SDK capabilities​

debox-chat-nodejs-sdk provides:

  • Bot initialization: NewBotAPI(apiKey, apiSecret)
  • Send message: bot.Send(...)
  • Long polling updates: GetUpdates / GetUpdatesChan
  • Inline keyboard and callback handling
  • Edit message: NewEditMessageText(...) / NewEditMessageTextAndMarkup(...)

2. Receiving mode notes​

This guide uses Long Polling. Before running it, clear any Webhook URL configured in BotMother; otherwise Long Polling is not a valid receiving path. For mode selection and switching, see the DeBox Bot Development Overview. For Webhook implementation, see DeBox Bot Go SDK Webhook.

3. Install and init​

3.1 Install​

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

Or clone and install locally:

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

3.2 Credentials​

The Bot details page in BotMother displays App Key and App Secret. Map them to the SDK parameters as follows:

  • App Key -> API_KEY (required)
  • App Secret -> API_SECRET (recommended)

See Credentials in the DeBox Bot Development Overview for the complete mapping and storage rules.

Set environment variables:

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

3.3 First message​

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. Receive messages with 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. Parse mode constants​

SDK constants:

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

For parse_mode, content, media URL, and length rules, see the OpenAPI message fields.

6. Inline keyboard + callback​

const markup = boxbotapi.NewInlineKeyboardMarkup(
  boxbotapi.NewInlineKeyboardRow(
    boxbotapi.NewInlineKeyboardButtonData("Details", "detail"),
    boxbotapi.NewInlineKeyboardButtonURL("Open docs", "https://docs.debox.pro"),
  ),
);

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

Handle callback:

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 routing fields​

Pass chat_id and chat_type to the SDK constructors according to the OpenAPI routing rules.

8. Common issues​

  1. No updates received:
  • Check webhook status first (mutually exclusive with polling).
  • Ensure boxbotapi.MessageListener = true.
  1. Request failed with auth error:
  • Check API_KEY/API_SECRET and signature-related headers.
  1. Media send failed: