在10分钟内将您的 Telegram 机器人复刻到 DeBox

在10分钟内将您的 Telegram 机器人复刻到 DeBox

本指南将帮助开发者将现有的 Telegram 机器人迁移到 DeBox 平台，详细说明两者功能的对应关系以及迁移所需的具体步骤。

---

1. 获取 DeBox 机器人 API Key

Telegram: 在 Telegram 中，您通过 BotFather 创建机器人并获取 Bot Token。

DeBox: 在 DeBox 中，您可通过更为直观的图形界面完成注册并获取 API Key：

1. 访问 DeBox APP 并连接钱包，完成账户注册和账户基本信息设置。
2. 访问 DeBox 开放平台，在机器人信息页面获取 API Key。

---

2. 更换 SDK 依赖

将您的 Telegram Bot SDK 更换为 DeBox 的 SDK：

Telegram:

import tgbotapi "github.com/go-telegram-bot-api/telegram-bot-api/v5"

bot, err := tgbotapi.NewBotAPI("<YOUR_BOT_TOKEN_HERE>")

该实例中示范的 Telegram 交互代码，来自 Telegram 官方示例 From BotFather to 'Hello World'

DeBox:

import boxbotapi "github.com/debox-pro/debox-chat-go-sdk/boxbotapi"

bot, err := boxbotapi.NewBotAPI("<YOUR_API_KEY>")

---

3. 接收消息（监听用户指令）

Telegram: 提供两种方式接收消息：Webhook 和 轮询 方法接收消息。

DeBox 与 Telegram 相同，均提供两种方式接收消息：Webhook 和 轮询。注意：两者只能选择一种方式使用。

方式一：使用 Webhook

1. 设置 Webhook URL

   • Telegram: 需要手写请求来设置 Webhook URL:

     curl -F "url=https://your-domain.com/your-webhook-path" https://api.telegram.org/bot<YOUR_BOT_TOKEN>/setWebhook
     curl https://api.telegram.org/bot<YOUR_BOT_TOKEN>/deleteWebhook

   • DeBox: 访问 DeBox 开放平台 机器人配置页，通过图形界面即可设置 Webhook URL，无需提前编写代码。

   • 配置完成后，系统会自动生成 Webhook Key，用于验证请求来源。

2. 接收消息回调

   • Telegram: 收到消息时，接收 JSON 格式的更新数据。

   • DeBox: 与 Telegram 相同，收到消息时，接收 JSON 格式的更新数据。，回调参数如下：

     {
     "from_user_id": "xx",   // 消息发送者的 DeBox ID
     "to_user_id": "xx",     // 消息接收者的 DeBox ID（机器人）
     "language": "en",       // 消息语言类型 {en, zh}
     "group_id": "xx",       // 群组消息的群组 ID，私聊则为空
     "mention_users": "xx",  // 消息中 @ 的用户列表
     "message": "xx",        // 去除 @ 标签后的消息内容
     "message_raw": "xx"     // 完整消息内容
     }

   • 验证请求来源: 在 Webhook 回调中，DeBox 会添加特殊 header X-API-KEY = Webhook Key，您可用它验证消息来源：

     if c.GetHeader("X-API-KEY") != WebhookKey {
         // 非法请求，拒绝处理
         return
     }

方式二：使用 SDK 接收消息

Telegram: 使用 GetUpdatesChan 方法轮询消息：

u := tgbotapi.NewUpdate(0)
u.Timeout = 60
updates := bot.GetUpdatesChan(u)

for update := range updates {
    if update.Message != nil {
        log.Printf("[%s] %s", update.Message.From.UserName, update.Message.Text)
    }
}

DeBox: 提供相同的接口，您无需修改代码：

u := boxbotapi.NewUpdate(0)
u.Timeout = 60
updates := bot.GetUpdatesChan(u)

for update := range updates {
    if update.Message != nil {
        log.Printf("[%s] %s", update.Message.From.UserName, update.Message.Text)
    }
}

详细教程，您可参考DeBox GO-SDK#接收消息更新

注意：如果设置了 Webhook URL，SDK 的消息更新功能将被忽略。

---

4. 发送消息

方式一：使用 HTTP API

Telegram:

curl -X POST \
    https://api.telegram.org/bot<BOT_TOKEN>/sendMessage \
    -H 'Content-Type: application/json' \
    -d '{"chat_id":<CHAT_ID>,"text":"Hello world!"}'

DeBox: 区分私聊和群组消息发送：

私聊消息：

curl -X POST -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d '{"to_user_id":"user_id","object_name":"text","content":"Hello world!"}' \
    "https://open.debox.pro/openapi/messages/private/send"

群组消息：

curl -X POST -H "Content-Type: application/json" \
    -H "X-API-KEY: YOUR_API_KEY" \
    -d '{"group_id":"group_id","object_name":"text","content":"Hello group!"}' \
    "https://open.debox.pro/openapi/messages/group/send"

详细方式可参考：DeBox API

方式二：使用 SDK

Telegram:

// 发送文本消息
msg := tgbotapi.NewMessage(chatId, "Hello world!")
bot.Send(msg)

// 发送 Markdown 消息
msg := tgbotapi.NewMessage(chatId, "*Bold* text")
msg.ParseMode = tgbotapi.ModeMarkdown
bot.Send(msg)

// 发送 HTML 消息
msg := tgbotapi.NewMessage(chatId, "<b>Bold</b> text")
msg.ParseMode = tgbotapi.ModeHTML
bot.Send(msg)

DeBox: 与 Telegram 类似，同样支持文本、Markdown 和 HTML 格式：

// 发送文本消息
msg := boxbotapi.NewMessage(chatId, chatType, "Hello world!")
bot.Send(msg)

// 发送 Markdown 消息
msg := boxbotapi.NewMessage(chatId, chatType, "#title,\nBold text")
msg.ParseMode = boxbotapi.ModeMarkdownV2
bot.Send(msg)

// 发送 HTML 消息
msg := boxbotapi.NewMessage(chatId, chatType, "<b>Bold</b> text")
msg.ParseMode = boxbotapi.ModeHTML
bot.Send(msg)
// 注意：chatType 需指定为 "private" 或 "group"

---

5. 消息按钮菜单

创建和发送按钮菜单

Telegram:

keyboard := tgbotapi.NewInlineKeyboardMarkup(
    tgbotapi.NewInlineKeyboardRow(
        tgbotapi.NewInlineKeyboardButtonData("Button", "callback_data"),
    ),
)
msg := tgbotapi.NewMessage(chatId, "Please click the button")
msg.ReplyMarkup = keyboard
bot.Send(msg)

DeBox: 支持更丰富的按钮功能，包括彩色按钮：

keyboard := boxbotapi.NewInlineKeyboardMarkup(
    boxbotapi.NewInlineKeyboardRow(
        boxbotapi.NewInlineKeyboardButtonURL("访问网站", "https://example.com"),
    ),
    boxbotapi.NewInlineKeyboardRow(
        boxbotapi.NewInlineKeyboardButtonDataWithColor("彩色按钮", "", "callback_data", "15%", "#ff0000"),
    ),
)
msg := boxbotapi.NewMessage(chatId, chatType, "请点击下方按钮")
msg.ReplyMarkup = keyboard
bot.Send(msg)

---

6. 配置指令

Telegram: 使用 BotFather 的命令行界面设置指令。

DeBox: 通过直观的图形界面配置指令：

1. 在开放平台的 Configure Bot → Configure commands 图形界面中，您可以:

   • 添加新指令
   • 编辑现有指令
   • 设置指令描述
   • 预览指令效果

2. 用户与机器人私聊时，输入 / 会弹出您配置的指令菜单，用户可一键点击发送。

3. 处理指令的代码几乎不需要更改：

Telegram:

if strings.HasPrefix(message.Text, "/") {
    switch message.Text {
    case "/start":
        // 处理 start 命令
    case "/help":
        // 处理 help 命令
    }
}

DeBox: 同样的代码可以继续使用

if strings.HasPrefix(message.Text, "/") {
    switch message.Text {
    case "/start":
        // 处理 start 命令
    case "/help":
        // 处理 help 命令
    }
}

---

常见问题

1. 消息接收不到

   • 检查是否同时设置了 Webhook URL 和使用 SDK。在 DeBox 中，Webhook URL 优先级高于 SDK。Webhook URL 设置后，SDK 的消息更新功能将失效。

2. 群组消息无法接收

   • 默认只接收 @ 机器人的消息。
   • 在开放平台图形界面中勾选 Monitor group message 选项开启所有群组消息监听。
   • 注意：非必要请勿开启此功能，避免过多消息回调。

3. Webhook Key 变更

   • 每次修改 Webhook URL 后，Webhook Key 都会自动更新。确保安全

4. 消息过期时间

   • DeBox 机器人收到的每条消息将在 DeBox 服务器上仅保留 1 分钟。

---

参考资源

• DeBox 指令机器人开发指南
• DeBox 开放平台 API 文档
• DeBox GO SDK 使用文档