Bot Guide

DeBox 聊天机器人使用指南

01. DeBox 聊天机器人能做什么？

DeBox 聊天机器人是一个DeBox用户。它具有普通用户的所有功能，如发送消息、发布动态、加入群聊、建设主页等，同时，具备如下独特功能：

可自由向用户发送消息；
可配置指令，便利地和粉丝互动；
可添加到群中，在众多群中得到曝光，提供服务；
可向粉丝进行通知推送；
可代表品牌方，7x24全天候提供服务；
可作为积分支付的交易对手方；
独特Bot标记，标识其机器人身份；
主页可配置，以公众号形式，服务粉丝；
允许二次开发，通过webhook回调支持无上限的功能；
完全兼容 Telegram 机器人 api，若您已有成熟的 Telegram 机器人，只需极少的调整就可在 DeBox 复刻（参考：在10分钟内将您的 Telegram 机器人复刻到 DeBox）；
......

无限功能，尽在想象！

02. 如何注册 DeBox 聊天机器人？

注册为 DeBox 用户

DeBox 聊天机器人需要使用一个现有的 DeBox 账户。若您的钱包未注册 DeBox，需要您访问 https://app.debox.pro/ ，连接对应钱包即可完成注册。

该账户作为 DeBox 聊天机器人账户，昵称、头像、简介、积分等数据将最终作为机器人属性直接呈现给粉丝，所以请认真配置该账户的昵称和头像，比如用开发者的品牌名做昵称，用品牌LOGO做头像。

申请成为 DeBox 聊天机器人

访问 https://developer.debox.pro ，点击Connect your wallet，通过 Metamask 连接欲成为机器人的钱包地址，签名完成登录，即可进入 DeBox 聊天机器人信息页面。
信息页中：
- App ID：注册成为机器人后获得。该聊天机器人的唯一 Id。调用某些 DeBox 开放平台 Api 时所必需；
- API Key：点击 Get 按钮，签名验证账号所有权后获得。调用某些 DeBox 开放平台 Api 时所必需；
- App Secret：点击 Apply 按钮，完成 KYC 后获得。调用某些 DeBox 开放平台支付、转账等敏感 Api 时所必需；
- App Domain：可在此配置 Webhook 白名单域名。使用外部 Webhook 回调时所必需。后续配置的外部 Webhook 回调 URL 须为该可信域名的子域名；
在获取 API Key 并且完成 App Domain 设置后，您可以进入 Bot 选项卡，设定 Webhook Url，完成 DeBox 聊天机器人 Webhook 功能的激活：
- 在此处设置好接收 Webhook 回调的 URL 后，点击 Apply 完成申请，即可激活 DeBox 聊天机器人。
完成上述步骤后，该 DeBox 账号将在 DeBox 中获得 BOT 标识，拥有完整机器人功能。

03. 配置 DeBox 聊天机器人

完成 DeBox 聊天机器人的注册后，您可以通过 DeBox 聊天机器人的身份，调用 DeBox 开放平台 API，完成各种与 DeBox 用户的交互。
同时，您可以在上文配置好的 Webhook Url 中接收到用户发送给该 DeBox 聊天机器人的消息。您可在配置的 Webhook 回调中完成消息处理，并根据不同指令，设计数据查询、消息发送、大模型调用等独特的、自定义的业务处理逻辑。
Webhook Url 使用方式：
- 当配置了 Webhook Url 的 DeBox 聊天机器人收到消息时，DeBox将主动以 POST 方式发送如下 json 结构体到设置好的 Webhook Url：
```
{
  "from_user_id": "xx",
  "to_user_id": "xx",
  "language": "en",
  "group_id": "xx",
  "mention_users": "xx",
  "message": "xx",
  "message_raw": "xx"
}
```
- 其中，参数含义如下：
  - from_user_id: 消息发送者的 DeBox id；
  - to_user_id: 消息接受者的 DeBox id，此处即为本机器人的 DeBox id；
  - language: 消息的语言类型，取值为 {en, zh} ；
  - group_id: 若消息来自 DeBox 群组，则为该群组的 DeBox id；若消息来自于用户私聊，则为 ""（空白字符串）；
  - mention_users: 本条消息中的 @ 用户列表；
  - message: 去除 @ 标签后的消息内容；
  - message_raw: 包括了 @ 标签的消息完整内容.
- 同时，该消息中会包含以下 header：
  - headers["X-API-KEY"]=Webhook Key
- 您可在接受 Webhook 回调的服务器上完成用户向 DeBox 聊天机器人发送的消息的解析，并根据消息的不同，按照您的设计，完成独特的业务逻辑，如数据查询、消息发送、大模型调用等。
- 我们强烈建议您在自己的 Webhook 回调函数中对 X-API-KEY header 进行校验，以确认请求来自DeBox系统。
若您在接受 Webhook 消息并完成处理后，希望从机器人账号发送消息给 DeBox 用户，您可参考 DeBox 开放平台文档中提供的 API 指引。
- 示例：群聊、私聊发消息API，可参考文档 https://docs.debox.pro/zh/APIs/SendingMessages

Webhook 回调函数示例（go语言）：

package handler

import (
  "bytes"
  "encoding/json"
  "fmt"
  "io"
  "net/http"
  "time"

  "github.com/gin-gonic/gin"
)

const (
  WebhookKey = "W2Tj8ybkLQRU3giI" // Webhook key, 注意在更换 webhook 地址后会变
  ApiKey     = "idsBhWq4wD1U7wL4" // 机器人账号的 API Key，在开放平台机器人页面首页获取
)

type RobotMsgReceive struct {
  FromUserId   string `json:"from_user_id"`
  ToUserId     string `json:"to_user_id"`
  Language     string `json:"language"`
  GroupId      string `json:"group_id"`
  Message      string `json:"message"`
  MessageRaw   string `json:"message_raw"`
  MentionUsers string `json:"mention_users"`
}

// ExampleWebhookHandler 处理来自DeBox的webhook回调
func ExampleWebhookHandler(c *gin.Context) {
  // 从请求头中获取 X-API-KEY，检验是否来自 DeBox 服务器
  if c.GetHeader("X-API-KEY") != WebhookKey {
    c.JSON(http.StatusUnauthorized, gin.H{
      "message": "ErrorInvalidParam: Invalid X-API-KEY",
    })
    return
  }

  // 解析请求体中的 JSON 数据
  var robotMsg RobotMsgReceive
  if err := c.ShouldBindJSON(&robotMsg); err != nil {
    fmt.Printf("解析请求失败: %v\n", err)
    c.JSON(http.StatusBadRequest, gin.H{
      "message": fmt.Sprintf("解析请求失败: %v", err),
    })
    return
  }

  // 收到消息后，可根据设计的机器人功能，按照消息内容作对应处理，并生成回复：
  content := fmt.Sprintf("我收到了%s发来的消息: %s", robotMsg.FromUserId, robotMsg.Message)

  // 构造回复消息
  msgToSend := RobotMsgSend{
    ObjectName: "text",
    FromUserId: robotMsg.ToUserId,
    GroupId:    robotMsg.GroupId,
    ToUserId:   robotMsg.FromUserId,
    Content:    content,
  }

  // 发送回复消息给用户
  if err := sendMessage(msgToSend); err != nil {
    fmt.Printf("发送消息失败: %v\n", err)
  } else {
    fmt.Println("发送消息成功")
  }
}

type RobotMsgSend struct {
  FromUserId string `json:"from_user_id"`
  ToUserId   string `json:"to_user_id"`
  GroupId    string `json:"group_id"`
  ObjectName string `json:"object_name"`
  MsgType    string `json:"msg_type"`
  Language   string `json:"language"`
  Message    string `json:"message"`
  Content    string `json:"content"`
}

// sendMessage 发送消息到DeBox API
func sendMessage(msg RobotMsgSend) error {
  // 根据是否有群组ID决定发送URL
  var sendURL string
  timeout := 10 * time.Second

  if msg.GroupId != "" {
    sendURL = "https://open.debox.pro/openapi/messages/group/send"
  } else {
    sendURL = "https://open.debox.pro/openapi/messages/private/send"
  }

  // 将数据转为JSON
  jsonData, err := json.Marshal(msg)
  if err != nil {
    return fmt.Errorf("JSON编码失败: %w", err)
  }

  // 创建请求
  req, err := http.NewRequest(http.MethodPost, sendURL, bytes.NewBuffer(jsonData))
  if err != nil {
    return fmt.Errorf("创建请求失败: %w", err)
  }

  // 设置请求头
  req.Header.Set("Content-Type", "application/json")
  req.Header.Set("X-API-KEY", ApiKey)

  // 发送请求
  client := &http.Client{Timeout: timeout}
  resp, err := client.Do(req)
  if err != nil {
    return fmt.Errorf("发送请求失败: %w", err)
  }
  defer resp.Body.Close()

  // 读取响应体
  respBody, err := io.ReadAll(resp.Body)
  if err != nil {
    return fmt.Errorf("读取响应失败: %w", err)
  }

  // 检查响应状态码
  if resp.StatusCode != http.StatusOK {
    return fmt.Errorf("请求失败，状态码: %d, 响应: %s", resp.StatusCode, string(respBody))
  }

  return nil
}

更多属性配置：图-1: Bot配置页面
- Webhook Url：如上所述，配置好 Webhook URL 后，您可在此 URL 中接收到 DeBox 用户发送给该 DeBox 聊天机器人的消息
- Webhook Key：配置好 Webhook URL 后自动生成的密钥，在 Webhook 回调中位于 X-API-KEY header 中，用于验证请求来源，确保请求来自 DeBox 系统。请注意：每次修改 Webhook Url 后，Webhook Key 都会更新
- Monitor group message（监听群组消息）：
  - 开启时，Bot 所在的群组中，所有用户发送的所有消息均会回调 Webhook；
  - 未开启时，Bot 所在的群组中，仅用户 @ 该 Bot 的消息才会回调 Webhook；
  - 注意：非必要情况下请勿开启此功能，以避免过多的消息回调。
- Published Bot（发布 Bot）：
  - 申请将 Bot 发布到 Bot 市场，使其能够被更多用户访问和使用。
  - 需确保 Bot 经过充分测试并已开发完善，否则申请可能被拒绝。
- Configure Bot（Bot 主页配置）
  - Configure services（Bot 主页的服务）：配置 Bot 提供的各项功能和服务。
  - Configure community（Bot 主页的社区）：配置 Bot 所关联的社区信息。
  - Configure commands（Bot 指令配置）：配置 Bot 支持的指令列表：
    - 可通过“添加新指令”按钮新增 Bot 指令。
    - 用户于Bot的对话框中输入 "/" 时，会弹出指令菜单，显示指令与描述。用户可以点击弹出的指令快速发送
- 保存与发布
  - 点击 “Save and Publish” 按钮，保存当前配置并发布 Bot 设置。

04. 配置机器人指令，通过指令和用户互动

聊天机器人可以通过设置指令来规范用户消息、方便用户使用、方便 Webhook 后台解析。
您可以根据机器人的功能定位，为其配置简单、易于理解的指令，如：
- 为价格播报机器人配置指令 /BTC、 /HOT Token List；
- 为新闻机器人配置指令 /News 、 /HOT News；
开发者可以通过【Bot】【Configure Bot】【Configure commands】来添加、删除、编辑指令；
用户进入和机器人的私聊界面后，通过"/"可唤起开发者所有已配置的指令，点击即可一键发送给机器人；
用户点击发送的指令将会作为一条正常消息触发机器人的 Webhook 回调，内容为指令 "/" 后的内容。您可在机器人的 Webhook 回调函数中对此针对性作解析和处理。

参考：上文图-1

05. 发布 DeBox 聊天机器人

经过上文配置和开发后，恭喜您！已经拥有了能处理指令的 DeBox 聊天机器人！
开发者自测通过后，便可提交机器人市场审核；
提交审核后，管理员会进一步对机器人功能进行评估和测试。若机器人品质符合管理规范，便可进入机器人市场，得到 DeBox 流量推送
若提交的机器人被审核人员驳回，开发者修改后可重新提交审核。
我们推荐您在提交前，于独立的 DeBox 群组中完成测试。

06. 如何设计一个好的聊天机器人？

由于 Bot 是一个 DeBox 用户，其昵称、头像、介绍等可在 DeBox 的 Web APP、APP 上进行配置。
我们建议您：
- 1. 由于 Bot 代表您的品牌，请设计好 Bot 的昵称、头像、介绍等信息。
- 1. 在 APP 端配置Bot 用户头像，一般使用品牌方的LOGO；
- 1. 在 APP 端配置Bot 名称，一般使用品牌方的名称；
- 1. 在 APP 端配置个性签名，该签名会作为机器人的remark，出现在指令列表里；
- 1. 在 APP 端的账号中发布动态，进行功能介绍、产品宣传、粉丝互动等；
- 1. 在机器人设置页配置机器人主页的服务和社区，以公众号形式，服务粉丝。
机器人示例：

07. 常见问题

访问 https://developer.debox.pro/ ，连接钱包时显示Failed: your address is not a DeBox account
- 该问题的的产生是因为您使用的账户还未在 DeBox 注册。您可访问 https://app.debox.pro/ ，连接对应钱包即可。

DeBox 聊天机器人使用指南​

01. DeBox 聊天机器人能做什么？​

02. 如何注册 DeBox 聊天机器人？​

注册为 DeBox 用户​

申请成为 DeBox 聊天机器人​

03. 配置 DeBox 聊天机器人​

04. 配置机器人指令，通过指令和用户互动​

05. 发布 DeBox 聊天机器人​

06. 如何设计一个好的聊天机器人？​

07. 常见问题​

DeBox 聊天机器人使用指南

01. DeBox 聊天机器人能做什么？

02. 如何注册 DeBox 聊天机器人？

注册为 DeBox 用户

申请成为 DeBox 聊天机器人

03. 配置 DeBox 聊天机器人

04. 配置机器人指令，通过指令和用户互动

05. 发布 DeBox 聊天机器人

06. 如何设计一个好的聊天机器人？

07. 常见问题