Skip to main content

DeBox Bot Python SDK Guide

Source repository:

1. SDK capabilities​

debox-chat-python-sdk provides:

  • Bot initialization: NewBotAPI(api_key, api_secret)
  • Message sending: bot.Send(...)
  • Long polling updates: GetUpdates / GetUpdatesChan
  • Inline keyboard + callback handling
  • Message editing: 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​

pip install git+https://github.com/debox-pro/debox-chat-python-sdk.git

Or clone and install locally:

git clone https://github.com/debox-pro/debox-chat-python-sdk.git
cd debox-chat-python-sdk
pip install -e .

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.

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

3.3 First message​

import os
import boxbotapi

bot = boxbotapi.NewBotAPI(
    os.getenv("DEBOX_BOT_API_KEY", ""),
    os.getenv("DEBOX_BOT_API_SECRET", ""),
)

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

sent = bot.Send(msg)
print("sent message_id=", sent.MessageID)

4. Receive messages with Long Polling​

import os
import boxbotapi
from boxbotapi import configs as cfg

cfg.Debug = False
cfg.MessageListener = True

bot = boxbotapi.NewBotAPI(
    os.getenv("DEBOX_BOT_API_KEY", ""),
    os.getenv("DEBOX_BOT_API_SECRET", ""),
)

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

for update in bot.GetUpdatesChan(u):
    if update.Message is not None:
        text = update.Message.Text or ""
        print("message:", text)

        reply = boxbotapi.NewMessage(
            update.Message.Chat.ID,
            update.Message.Chat.Type,
            f"Received: {text}",
        )
        reply.ParseMode = boxbotapi.ModeRichText
        bot.Send(reply)

    if update.CallbackQuery is not None:
        print("callback:", update.CallbackQuery.Data)

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​

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

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

Handle callback and edit message:

if update.CallbackQuery is not None:
    data = update.CallbackQuery.Data
    chat = update.CallbackQuery.Message.Chat
    message_id = update.CallbackQuery.Message.MessageID

    edit = boxbotapi.NewEditMessageText(chat.ID, chat.Type, message_id, f"clicked: {data}")
    edit.ParseMode = boxbotapi.ModeRichText
    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 cfg.MessageListener = True.
  1. Auth error:
  • Verify API_KEY/API_SECRET and header signature path.
  1. Media send failed: