跳到主要内容

DeBox 机器人 Go SDK 使用文档

源码仓库：

1. SDK 功能总览​

debox-chat-go-sdk 主要提供：

  • 机器人初始化：NewBotAPI(apiKey, apiSecret)
  • 发送消息：bot.Send(...)
  • Long Polling 收消息：GetUpdates / GetUpdatesChan
  • 按钮与回调：InlineKeyboardMarkup + CallbackQuery
  • 编辑消息：NewEditMessageText + bot.Send(...)

Webhook 已拆分为独立文档：

2. 收消息模式说明​

本文使用 Long Polling。运行前必须清空 BotMother 中已经配置的 Webhook URL，否则 Long Polling 不能用于收消息。模式选择和切换方法请查看DeBox 机器人开发总览，Webhook 实现请查看DeBox 机器人 Go SDK Webhook。

3. Long Polling（SDK 详细用法）​

3.1 安装 SDK​

go get github.com/debox-pro/debox-chat-go-sdk

3.2 准备凭证​

BotMother 的 Bot 详情页显示 App Key 和 App Secret，在 SDK 中按以下关系使用：

  • App Key → API_KEY（必须）
  • App Secret → API_SECRET（建议）

完整对应关系和保存要求请查看DeBox 机器人开发总览中的凭证说明。

3.3 初始化 Bot + 发送第一条消息​

package main

import (
    "log"

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

func main() {
    bot, err := boxbotapi.NewBotAPI("YOUR_APP_KEY", "YOUR_API_SECRET")
    if err != nil {
        log.Fatalf("init bot failed: %v", err)
    }

    // group: chatID=gid；private: chatID=目标用户的 user_id（与该用户的 uid、invite_code 值相同）
    msg := boxbotapi.NewMessage("cc0onr82", "group", "Hello from Go SDK")
    msg.ParseMode = boxbotapi.ModeRichText

    sent, err := bot.Send(msg)
    if err != nil {
        log.Fatalf("send failed: %v", err)
    }
    log.Printf("sent message_id=%s", sent.MessageID)
}

3.4 收消息方式 A：GetUpdatesChan（推荐）​

package main

import (
    "context"
    "log"

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

func main() {
    bot, err := boxbotapi.NewBotAPI("YOUR_APP_KEY", "YOUR_API_SECRET")
    if err != nil {
        log.Fatal(err)
    }

    // 必须打开监听开关
    boxbotapi.MessageListener = true

    cfg := boxbotapi.NewUpdate(0)
    cfg.Timeout = 30

    ctx := context.Background()
    updates := bot.GetUpdatesChan(cfg)

    for {
        select {
        case <-ctx.Done():
            bot.StopReceivingUpdates()
            return
        case upd := <-updates:
            if upd.Message != nil {
                log.Printf("from=%s chat=%s text=%s", upd.Message.From.UserId, upd.Message.Chat.ID, upd.Message.Text)
            }
            if upd.CallbackQuery != nil {
                log.Printf("callback=%s", upd.CallbackQuery.Data)
            }
        }
    }
}

3.5 收消息方式 B：GetUpdates（手动轮询）​

cfg := boxbotapi.NewUpdate(0)
cfg.Timeout = 30

updates, err := bot.GetUpdates(cfg)
if err != nil {
    log.Printf("get updates failed: %v", err)
    return
}

for _, upd := range updates {
    if upd.Message != nil {
        log.Println(upd.Message.Text)
    }
}

3.6 发送不同类型消息​

// MarkdownV2
m1 := boxbotapi.NewMessage(chatID, chatType, "*bold* _italic_")
m1.ParseMode = boxbotapi.ModeMarkdownV2
_, _ = bot.Send(m1)

// HTML
m2 := boxbotapi.NewMessage(chatID, chatType, "<b>Hello</b> <a href=\"https://docs.debox.pro\">docs</a>")
m2.ParseMode = boxbotapi.ModeHTML
_, _ = bot.Send(m2)

// 图片/视频/文件（文本填 URL）
m3 := boxbotapi.NewMessage(chatID, chatType, "https://example.com/a.png")
m3.ParseMode = boxbotapi.ModeImage
_, _ = bot.Send(m3)

可用 ParseMode：

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

chat_id、chat_type、parse_mode、content、媒体 URL 和长度规则请查看 OpenAPI 消息字段说明。

3.7 按钮与回调​

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

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

处理回调：

if upd.CallbackQuery != nil {
    data := upd.CallbackQuery.Data
    _ = data
}

3.8 编辑消息​

edit := boxbotapi.NewEditMessageText("cc0onr82", "group", "MESSAGE_ID", "编辑后的文本")
edit.ParseMode = boxbotapi.ModeRichText
_, err := bot.Send(edit)
if err != nil {
    log.Printf("edit failed: %v", err)
}