跳到主要内容

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。

如果你已经在开放平台配置 Webhook，Polling 可能收不到消息。Webhook 部署请看：

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

3.1 安装 SDK​

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

3.2 准备凭证​

从 DeBox 开放平台获取：

  • API_KEY（必须）
  • API_SECRET（建议）

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(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

content 填写规则（按 parse_mode）：

  • richtext（默认）：填写普通文本或富文本语义字符串，例如 你好，欢迎使用 DeBox Bot。
  • text：填写纯文本（不解析 Markdown/HTML），例如 plain text only。
  • Markdown：填写 Markdown 字符串，例如 **bold**。
  • MarkdownV2：填写 MarkdownV2 字符串（注意转义），例如 \\*bold\\*。
  • HTML：填写 HTML 片段字符串，例如 <b>Hello</b>。
  • image：content 填可公网访问的图片 URL，例如 https://cdn.example.com/a.png。
  • video：content 填可公网访问的视频 URL，例如 https://cdn.example.com/demo.mp4。
  • file：content 填可公网访问的文件 URL，例如 https://cdn.example.com/spec.pdf。
  • 文本类（richtext/text/Markdown/MarkdownV2/HTML）最大长度 5000 字符。

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)
}