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

Webhook and Long Polling are strictly mutually exclusive:

  • If webhook is configured in platform console, messages are delivered to webhook.
  • To use polling, clear webhook configuration first.

Webhook guide:

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​

Get from DeBox Open Platform:

  • API_KEY (required)
  • API_SECRET (recommended)
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 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​

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​

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 cfg.MessageListener = True.
  1. Auth error:
  • Verify API_KEY/API_SECRET and header signature path.
  1. Media send failed:
  • Ensure URL is public and directly accessible.