跳到主要内容

GO-SDK

DeBox 机器人 Go SDK 使用文档​

基本介绍​

debox-chat-go-sdk 是 ​DeBox 聊天机器人的官方 Golang SDK，对 DeBox 社交平台核心的 ​消息发送与接收 功能进行了封装。开发者可以借助该 SDK 快速高效地构建 DeBox 聊天机器人，共享 DeBox 生态的流量红利，实现技术价值与商业价值的双重提升。

通过 debox-chat-go-sdk，您可以轻松实现以下功能：

✅ ​发送消息：支持文本、Markdown、HTML、富文本、按钮菜单等多种消息格式。
✅ ​接收消息：实时监听用户消息和群聊信息，并做出自动化响应。
✅ ​处理指令：通过自定义指令与用户进行灵活互动。
✅ ​Webhook 扩展：可通过 Webhook 事件，实现更复杂的功能集成。

本指南将详细介绍 debox-chat-go-sdk 的主要功能，并提供完整的示例代码，帮助开发者快速上手并高效开发。

关于 DeBox 指令机器人​

DeBox 指令机器人是 DeBox 平台上的自动化交互主体，其作为一种特殊的用户，具备 发送和接收消息 的能力，并可通过 Webhook 与外部系统集成，适用于消息推送、指令交互、自动化运营等场景。更多介绍，参见 DeBox指令机器人开发指南

目录​

安装 SDK​

您可通过 Go 模块安装 SDK：

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

初始化 Bot​

使用 DeBox 机器人 SDK 的第一步是创建 BoxBotAPI 实例。您需要提供 Bot 的 API_KEY 完成机器人创建的身份验证。

您可在 DeBox开放平台 获取 Bot 的 API_KEY。参考 DeBox指令机器人开发指南

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

// 初始化 bot
func getBot() (*boxbotapi.BotAPI, error) {
    bot, err := boxbotapi.NewBotAPI("YOUR_BOT_API_KEY") // 请替换为你的 Bot 的 API_KEY
    if err != nil{
        log.Fatalf("Failed to initialize bot: %v", err)
        return nil, err
    }
    // 开启 Debug 模式，记录详细日志
    bot.Debug = true

    log.Printf("Authorized on account %s，bot start running！", bot.Self.Name)
    return bot, err
}

请务必保存好您的 API_KEY！任何拥有您的 API_KEY 的人都可以发送和接收来自您的 Bot 的消息！

接收消息更新​

DeBox机器人SDK提供了两种接收消息更新的方式：

  • 通过Go channel持续监听
  • 主动获取消息列表。

以下是这两种方法的具体使用示例。

重要提示

若您希望使用 DeBox Go SDK 来处理消息更新，请不要在 [开放平台机器人控制页] 设置 Webhook URL。一旦设置了 Webhook URL，DeBox Go SDK 的消息更新功能将被系统忽略，所有消息会被优先发送到您配置的 Webhook 地址。

1. 通过 go channel 获取消息更新​

使用 GetUpdatesChan 方法通过 go channel 来获取消息更新：

// 通过 go channel 来获取消息更新
func GetUpdatesChanExample() {
    // 初始化Bot
    bot, _ := getBot()
    
    // 设置消息更新参数
    updateConfig := boxbotapi.NewUpdate(0)
    updateConfig.Timeout = 60
    
    // 创建可取消的上下文
    ctx := context.Background()
    ctx, cancel := context.WithCancel(ctx)
    
    // 获取消息更新通道
    updates := bot.GetUpdatesChan(updateConfig)
    
    // 启动 goroutine 异步处理消息更新
    go receiveUpdates(ctx, updates)
    
    log.Println("Start listening for updates. Press enter to stop")
    
    // 等待用户按Enter键后停止处理
    bufio.NewReader(os.Stdin).ReadBytes('\n')
    cancel()
}

func receiveUpdates(ctx context.Context, updates boxbotapi.UpdatesChannel) {
    // 持续监听消息更新
    for {    
        select {
        // 如果上下文被取消，停止监听循环
        case <-ctx.Done():
            return
        // 接收并处理新消息
        case update := <-updates:
            handleUpdate(update)
        }
    }
}

// 根据消息类型分发处理逻辑
func handleUpdate(update boxbotapi.Update) {
    switch {
    // 处理文本消息
    case update.Message != nil:
        handleMessage(update.Message)
    // 处理按钮点击事件（功能未上线）
    case update.CallbackQuery != nil:
        handleButton(update.CallbackQuery)
    }
}

说明：

  • GetUpdatesChan 这个方法只允许你的机器人一次处理一个更新。请务必使用 goroutines 来并发处理更新，或者改用 webhooks。对于高流量机器人，建议使用 webhooks。

2. 通过列表获取消息更新​

如果您需要更灵活地控制消息轮询逻辑，可以直接使用 GetUpdates 方法获取消息更新列表：

// 主动获取获取过去1分钟内未读取的消息
// 注意：由于消息仅保留1分钟，需要定期轮询才能持续接收消息
func GetUpdatesExample() {
    // 初始化Bot
    bot, _ := getBot()
    
    // 创建更新配置
    updateConfig := boxbotapi.NewUpdate(0)  // 兼容 telegram API 的设计，目前无意义
    
    // 获取消息更新列表
    updates, err := bot.GetUpdates(updateConfig)
    if err != nil {
        log.Panic(err)
    }

    // 处理每条消息（按从旧到新的顺序）
    for _, update := range updates {    
        handleUpdate(updates)
    }
}

发送消息​

1. 发送普通文本消息​

// 发送消息时用到的参数
var (
    chatID    = "l3ixr31y"  // 目标群组 或 目标用户的 debox id 
    chatType  = "group"     // "group" 或 "private"
)

func SendMessageExample(chatId, chatType string) {
    // 初始化bot
    bot, _ := getBot()

    // 普通文本消息
    message   := "This is a example message from debox go SDK"

    // 建立消息结构体
    msg := boxbotapi.NewMessage(chatId, chatType, message)
    // 发送消息
    _, err := bot.Send(msg)
    if err != nil {
        log.Printf("An error occurred: %s", err.Error())
    }
    
}

2. 发送 Markdown 消息​

DeBox 机器人支持 Markdown 格式的消息，可用于创建结构化文本：

func SendMarkdownMessageExample(chatId, chatType string) {
    // 初始化bot
    bot, _ := getBot()
    
    // Markdown 类型的消息
    markdownMessage   := "#title,\nA test message from the test library in debox-bot-api"   

    // 建立消息结构体
    msg := boxbotapi.NewMessage(chatId, chatType, markdownMessage)
    // 设置消息解析形式
    msg.ParseMode = boxbotapi.ModeMarkdownV2
    // 发送消息
    _, err := bot.Send(msg)
    if err != nil {
        log.Printf("An error occurred: %s", err.Error())
    }
}

3. 发送 HTML 消息​

如果希望发送更丰富的格式化文本，可以使用 HTML 格式：

func SendHTMLMessageExample(chatId, chatType string) {
    // 初始化bot
    bot, _ := getBot()
    
    // HTML 类型的消息
    HTMLMessage   := "A test <b>html</b> <font color=\"red\">message</font><br/><a href=\"https://debox.pro\">debox</a>"   

    // 建立消息结构体
    msg := boxbotapi.NewMessage(chatId, chatType, HTMLMessage)
    // 设置消息解析形式
    msg.ParseMode = boxbotapi.ModeHTML
    // 发送消息
    _, err := bot.Send(msg)    
    if err != nil {
        log.Printf("An error occurred: %s", err.Error())
    }

}

4. 发送富文本消息​

富文本消息支持图片、超链接等 UI 组件，适用于更复杂的消息内容：

func SendRichTextExample(chatId, chatType string) {
    var imageOne = "https://data.debox.pro/dao/newpic/one.png"
    var imageTwo = "https://data.debox.pro/dao/newpic/two.png"
    var href = "https://app.debox.pro/"
    
    // 头部图片
    var uiImgHead = boxbotapi.UITagImg{
        Uitag:    "img",
        Src:      imageOne,
        Position: "head",
        Href:     href,
        Height:   "200",
    }
    jsonUIImgHead, _ := json.Marshal(uiImgHead)
    
    // 底部图片
    var uiImgFoot = boxbotapi.UITagImg{
        Uitag:    "img",
        Src:      imageTwo,
        Position: "foot",
        Href:     href,
        Height:   "300",
    }
    uiImgFootJson, _ := json.Marshal(uiImgFoot)
    
    // 超链接
    var uiA = boxbotapi.UITagA{
        Uitag: "a",
        Text:  "DeBox",
        Href:  href,
    }
    uiAJson, _ := json.Marshal(uiA)
    
    // 组合富文本内容
    RichTextContent := "richtext https://debox.pro " + string(jsonUIImgHead) + string(uiImgFootJson) + string(uiAJson)
    
    // 初始化bot
    bot, _ := getBot()
    
    // 建立消息结构体
    msg := boxbotapi.NewMessage(chatId, chatType, RichTextContent)
    // 发送消息
    _, err := bot.Send(msg)
    
    if err != nil {
        log.Printf("An error occurred: %s", err.Error())
    }
}

消息按钮菜单​

创建消息按钮菜单​

您可以创建消息按钮菜单，实现点击跳转等交互功能。 目前，每行最大支持 5 个按钮。更多的按钮将被隐藏。

func SendMenuExample(chatId, chatType string) error {
    // 初始化bot
    bot, _ := getBot()

    // 创建按钮
    // 消息正文
    menuMessageText = "<b>Menu 1</b><br/>A box button message."
    // 创建按钮菜单
    firstMenuMarkup = boxbotapi.NewInlineKeyboardMarkup(
        // 创建按钮菜单第一行
        boxbotapi.NewInlineKeyboardRow(
            // 第一行第一个按钮
            boxbotapi.NewInlineKeyboardButtonURL("url1", tokenUrl),
        ),
        // 创建按钮菜单第二行
        boxbotapi.NewInlineKeyboardRow(
            // 第二行第一个按钮
			boxbotapi.NewInlineKeyboardButtonDataWithColor("BOX", "", swapUrl, "15%", "#ff0000"),
            // 第二行第二个按钮
			boxbotapi.NewInlineKeyboardButtonDataWithColor("BTC", "", "https://debox.pro", "27.5%", "#00ff00"),
),
    )

    // 建立消息结构体
    msg := boxbotapi.NewMessage(chatId, chatType, menuMessageText)
    // 设置消息解析类型
    msg.ParseMode = boxbotapi.ModeHTML
    // 设置消息按钮菜单
    msg.ReplyMarkup = firstMenuMarkup
    // 发送消息
    _, err := bot.Send(msg)
    return err
}

处理用户命令​

您可以监听和处理用户发送的消息，进行处理后执行指定操作，回复用户消息。 命令是您可以在机器人面板中设置的、用户可以方便的一键回复的消息，以 "/" 起始。您可对此专门设置回复。

// 处理接收到的消息更新
func handleUpdate(update boxbotapi.Update) {
    // DeBox 可以根据你的 Bot 的活动发送多种类型的更新。您可以对此分别作处理。
    // 由于更新有多种类型，在一个 `Update` 结构体中，最多仅有一个字段会被设置为非 nil 值。请确保在尝试访问任何字段之前检查该字段是否为 nil。

    switch {
    // 处理消息
    case update.Message != nil:
        handleMessage(update.Message)
    // 处理按钮点击事件（功能未上线）
    case update.CallbackQuery != nil:
        handleButton(update.CallbackQuery)
    }
}

func handleMessage(message *boxbotapi.Message) {
    // 打印收到的消息
    log.Printf("%s wrote %s",  message.From.Name, text)

    // 处理 "/" 指令消息：
    if strings.HasPrefix(text, "/") {
        switch text {
        case "/menu":
            // 您可自定义对于指令的响应，如发送消息，执行操作等
            err := sendMenu(message.Chat.ID, message.Chat.Type)
        case "/menu2":
            err := sendMenu2(message.Chat.ID, message.Chat.Type)
        }
    } else if len(text) > 0 {
        // 处理其它消息
        // 这里从传入消息中获取 Chat ID 和 Text，并简单的回传发来的消息
        msg := boxbotapi.NewMessage(message.Chat.ID, message.Chat.Type, message.Text)
        // 发送消息回复
        _, err := bot.Send(msg)
    }
    
    if err != nil {
        log.Printf("An error occurred: %s", err.Error())
    }
}

使用 DeBox 开放平台 API​

在您完成机器人的注册，获得 API_KEY 后，您就可以使用多种多样的 DeBox 开放平台 API 了！您可通过 DeBox 开放平台 API 与 DeBox 交互，获取您的产品构建所需的信息，完成各种独特的功能。

您可参考 DeBox 开放平台 API 文档 获取更多信息。

某些 DeBox 开放平台 API 需要使用签名进行身份验证。各个 API 对应的签名的计算见开放平台对应 API 文档。以下是一个生成签名、调用 DeBox 开放平台获取用户信息 API 的示例：

import (
    "crypto/sha1"
    "encoding/json"
    "fmt"
    "io"
    "math/rand"
    "strconv"
    "time"
)

// 生成 API 所需的签名
func getSignature(appSecret string) (nonce, timestamp, signature string) {
    nonceInt := rand.Int()
    nonce = strconv.Itoa(nonceInt)
    timeInt64 := time.Now().Unix()
    timestamp = strconv.FormatInt(timeInt64, 10)
    h := sha1.New()
    _, _ = io.WriteString(h, appSecret+nonce+timestamp)
    signature = fmt.Sprintf("%x", h.Sum(nil))
    return
}

// 调用用户信息 API
func TestUserInfot(t *testing.T) {
    url := "https://open.debox.pro/openapi/user/info?user_id=uvg2p6ho"
    
    nonce, timestamp, signature := getSignature("app_secret")  
    var headers = map[string]string{
        "X-API-KEY": TestToken,
        "nonce":     nonce,
        "timestamp": timestamp,
        "signature": signature,
    }
    
    var resp = make(map[string]interface{})
    err := HttpGet2Obj(url, headers, &resp)
    if err != nil {
        fmt.Println("send chat message fail:", err)
        return
    }
    
    strRes, err := json.Marshal(resp)
    if err != nil {
        fmt.Println("error:" + err.Error())
        return
    }
    
    fmt.Println("UserInfot_Test success." + string(strRes))
}

参考使用示例​

我们提供了一个使用了各个 DeBox GO SDK 功能的示例，供您参考：

使用示例代码：

package main

import (
    "encoding/json"
    "log"
    "testing"

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

var (
    TestToken = "oPM1uUmE6mIitDC8" //replace with your token
    ChatID    = "l3ixp32y"
    // TestToken       = "pPpHtOTtXsE6i5u6" //replace with your token
    // ChatID          = "ymor0jin"
    ChatType        = "group" //private,group
    swapUrl         = "https://deswap.pro/?from_chain_id=1&from_address=0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE&to_chain_id=1&to_address=0x32b77729cd87f1ef2bea4c650c16f89f08472c69&native=true"
    numericKeyboard = boxbotapi.NewInlineKeyboardMarkup(
        boxbotapi.NewInlineKeyboardRow(
            boxbotapi.NewInlineKeyboardButtonURL("debox", "https://debox.pro"),
            boxbotapi.NewInlineKeyboardButtonData("2", "2"),
            boxbotapi.NewInlineKeyboardButtonData("3", "3"),
        ),
        boxbotapi.NewInlineKeyboardRow(
            boxbotapi.NewInlineKeyboardButtonDataWithColor("BOX", "", swapUrl, "15%", "#ff0000"),
            boxbotapi.NewInlineKeyboardButtonDataWithColor("BTC", "", "https://debox.pro", "27.5%", "#00ff00"),
        ),
    )
)

type testLogger struct {
    t *testing.T
}

func (t testLogger) Println(v ...interface{}) {
    t.t.Log(v...)
}

func (t testLogger) Printf(format string, v ...interface{}) {
    t.t.Logf(format, v...)
}

func getBot(t *testing.T) (*boxbotapi.BotAPI, error) {
    bot, err := boxbotapi.NewBotAPI(TestToken)
    bot.Debug = true

    logger := testLogger{t}
    boxbotapi.SetLogger(logger)

    if err != nil {
        t.Error(err)
    }

    return bot, err
}

func TestNewBotAPI_notoken(t *testing.T) {
    _, err := boxbotapi.NewBotAPI("")

    if err == nil {
        t.Error(err)
    }
}

func TestGetUpdates(t *testing.T) {
    bot, _ := getBot(t)

    updateConfig := boxbotapi.NewUpdate(0)

    updates, err := bot.GetUpdates(updateConfig)
    if err != nil {
        t.Error(err)
    }
    for _, update := range updates {
        log.Printf("%+v\n", update)
    }
}

func TestSendMarkdownMessage(t *testing.T) {
    bot, _ := getBot(t)

    msg := boxbotapi.NewMessage(ChatID, ChatType, "#title,\nA test message from the test library in debox-bot-api")
    msg.ParseMode = boxbotapi.ModeMarkdownV2
    _, err := bot.Send(msg)

    if err != nil {
        t.Error(err)
    }
}
func TestSendHTMLMessage(t *testing.T) {
    bot, _ := getBot(t)

    msg := boxbotapi.NewMessage(ChatID, ChatType, "A test <b>html</b> <font color=\"red\">message</font><br/><a href=\"https://debox.pro\">debox</a>")
    msg.ParseMode = boxbotapi.ModeHTML
    _, err := bot.Send(msg)

    if err != nil {
        t.Error(err)
    }
}
func TestSendRichText(t *testing.T) {
    var imageOne = "https://data.debox.pro/dao/newpic/one.png"
    var imageTwo = "https://data.debox.pro/dao/newpic/two.png"
    var href = "https://app.debox.pro/"
    var uiImgHead = boxbotapi.UITagImg{
        Uitag:    "img",
        Src:      imageOne,
        Position: "head",
        Href:     href,
        Height:   "200",
    }
    jsonUIImgHead, _ := json.Marshal(uiImgHead)

    var uiImgFoot = boxbotapi.UITagImg{
        Uitag:    "img",
        Src:      imageTwo,
        Position: "foot",
        Href:     href,
        Height:   "300",
    }
    uiImgFootJson, _ := json.Marshal(uiImgFoot)

    var uiA = boxbotapi.UITagA{
        Uitag: "a",
        Text:  "DeBox",
        Href:  href,
    }
    uiAJson, _ := json.Marshal(uiA)
    content := "richtext https://debox.pro " + string(jsonUIImgHead) + string(uiImgFootJson) + string(uiAJson)
    // send
    bot, _ := getBot(t)

    msg := boxbotapi.NewMessage(ChatID, ChatType, content)
    // msg.ParseMode = boxbotapi.ModeRichText
    _, err := bot.Send(msg)

    if err != nil {
        t.Error(err)
    }
}

func TestGetAndSend_Messages(t *testing.T) {
    // bot, err := boxbotapi.NewBotAPI(os.Getenv("DEBOX_APITOKEN"))
    bot, err := boxbotapi.NewBotAPI(TestToken)
    if err != nil {
        log.Panic(err)
    }

    bot.Debug = true

    log.Printf("Authorized on account %s", bot.Self.Name)

    u := boxbotapi.NewUpdate(0)
    u.Timeout = 60

    updates := bot.GetUpdatesChan(u)

    // Loop through each update.
    for update := range updates {
        // Check if we've gotten a message update.
        if update.Message != nil {
            // Construct a new message from the given chat ID and containing
            // the text that we received.
            msg := boxbotapi.NewMessage(update.Message.Chat.ID, update.Message.Chat.Type, update.Message.Text)

            // If the message was open, add a copy of our numeric keyboard.
            switch update.Message.Text {
            case "/menu":
                msg.ReplyMarkup = numericKeyboard
            case "help":
                msg.Text = "I understand /sayhi and /status."
            case "sayhi":
                msg.Text = "Hi :)"
            case "status":
                msg.Text = "I'm ok."
            }

            // Send the message.
            if _, err = bot.Send(msg); err != nil {
                panic(err)
            }
        } else if update.CallbackQuery != nil {
            // Respond to the callback query, telling DeBox to show the user
            // a message with the data received.
            callback := boxbotapi.NewCallback(update.CallbackQuery.ID, update.CallbackQuery.Data)
            if _, err := bot.Request(callback); err != nil {
                panic(err)
            }

            // And finally, send a message containing the data received.
            msg := boxbotapi.NewMessage(update.CallbackQuery.Message.Chat.ID, update.CallbackQuery.Message.Chat.Type, update.CallbackQuery.Data)
            if _, err := bot.Send(msg); err != nil {
                panic(err)
            }
        }
    }
}

常见问题​

1. 我使用了 GetUpdates 或 GetUpdatesChan 方法来监听发送到机器人的消息，但是什么都没有收到？​

  • 您是否在 [开放平台机器人控制页] 设置了消息回调的 Webhook URL？若您希望使用 DeBox Go SDK 来处理消息更新，请不要在 开放平台机器人控制页 设置 Webhook URL。一旦设置了 Webhook URL，DeBox Go SDK 的消息更新功能将被系统忽略，所有消息会被优先发送到您配置的 Webhook URL 地址。
  • 若您使用 GetUpdates 方法，请注意，该方法仅能够获取最近 1 分钟机器人接收到、且未被读取的消息。若机器人接收到的消息未在 1 分钟内被 GetUpdates 或 GetUpdatesChan 方法获得，则您将无法再次获得该消息。

2. 我使用 GetUpdates 或 GetUpdatesChan 方法，仅能获取 DeBox 用户私聊给机器人的消息，无法获取机器人加入的群聊中的消息？​

  • 您若希望监听机器人加入的群聊中的消息，您需要在 [开放平台机器人控制页] 中打开 Monitor group message（监听群组消息） 选项：
    • 该选项开启时，Bot 所在的群组中，所有用户发送的所有消息均会发送到机器人；
    • 该选项未开启时，Bot 所在的群组中，仅用户 @ 该 Bot 的消息才会发送到机器人；
    • 注意：非必要情况下请勿开启此功能，以避免过多的消息回调。