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 document focuses on Long Polling mode.

Webhook and Long Polling are strictly mutually exclusive:

  • If webhook is configured in platform console, webhook becomes the active receiving path.
  • To receive updates via polling, clear webhook config first.

Webhook usage is covered separately:

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​

Get from DeBox Open Platform:

  • API_KEY (required)
  • API_SECRET (recommended)

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 and content rules​

SDK constants:

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

content rules:

  • richtext / Markdown / MarkdownV2 / HTML: send text content.
  • image / video / file: content must be a publicly reachable URL.
  • Text content max length is 5000 characters.

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​

When sending/editing messages:

  • chat_type=group -> chat_id must be group gid
  • chat_type=private -> chat_id must be user user_id (invite code)

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:
  • Ensure URL is public and directly accessible.