跳到主要内容

DeBox 机器人 Python SDK 使用文档

源码仓库：

1. SDK 功能总览​

debox-chat-python-sdk 提供：

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

2. 收消息模式说明​

本文仅覆盖 Long Polling 模式。

Webhook 与 Long Polling 严格互斥：

  • 开放平台配置了 webhook 后，消息优先走 webhook。
  • 要使用轮询，先清空 webhook 配置。

Webhook 文档：

3. 安装与初始化​

3.1 安装 SDK​

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

或本地拉取安装：

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

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 发送第一条消息​

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. 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. 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. 按钮与回调​

markup = boxbotapi.NewInlineKeyboardMarkup(
    boxbotapi.NewInlineKeyboardRow(
        boxbotapi.NewInlineKeyboardButtonData("查看详情", "detail"),
        boxbotapi.NewInlineKeyboardButtonURL("打开文档", "https://docs.debox.pro"),
    )
)

msg = boxbotapi.NewMessage("cc0onr82", "group", "请选择")
msg.ParseMode = boxbotapi.ModeRichText
msg.ReplyMarkup = markup
bot.Send(msg)

处理回调并编辑消息：

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_type=group -> chat_id 填群 gid
  • chat_type=private -> chat_id 填用户 user_id（invite code）

8. 常见问题​

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