开发 Sibrel 机器人

创建你的第一个机器人

打开设置 → 机器人 → 创建机器人。你的主机可以关闭机器人创建功能。
选择由 a-z0-9_ 组成、长度 2–32 的用户名。请保存令牌：它只会显示一次。
在社区设置中添加该机器人，并只授予必要的权限。管理操作需要 MANAGE_BOTS。
在你的电脑或服务器上运行机器人程序。机器人账户本身不会执行任何代码。
使用签发该令牌的主机的 API 地址。

机器人只能在它已加入的社区频道中操作。机器人 API 不支持私聊和公开空间。

身份验证与密钥

Authorization: Bearer <BOT_TOKEN>

机器人的操作需要机器人令牌。创建或修改机器人、把机器人加入社区以及设置权限，则需要所有者或管理员的账户令牌。请把这两类凭据分开保管。

把令牌存放在环境变量中，绝不要写进浏览器代码或 Git。主机的数据库只保存令牌的哈希值。一旦令牌泄露，请立即撤销并重新签发。网关会通过查询字符串传递令牌，因此请在反向代理和监控日志中隐藏相关 URL。请使用 HTTPS/WSS。

最小可用示例

需要 Node.js 22+，并使用内置的 fetch 和 WebSocket。下载 ping-bot.en.mjs。该示例注册 /ping 命令，在频道中回复，并在断开后重新连接。

$env:SIBREL_API_URL = "https://api.example.org"
$env:SIBREL_BOT_TOKEN = "your-token"
node ./ping-bot.en.mjs

机器人 REST API

方法与路径	用途
GET /api/bots/me	个人资料、连接状态、命令和所在社区。
GET /api/bots/guilds	机器人已加入的社区。
GET /api/bots/guilds/:guildId/channels	可用频道。
GET /api/bots/channels/:channelId/messages?limit=20&before=:id	历史消息；每次请求最多 100 条。
POST /api/bots/messages	发送 channel_id 以及 content / embeds / components；reply_to_id 可选。
PATCH /api/bots/messages/:id	编辑机器人自己发送的消息。
DELETE /api/bots/messages/:id	软删除。mode=hard 需要相应权限。
POST /api/bots/channels/:id/typing	发送输入中状态；返回 204。
GET /api/bots/commands	列出已注册的命令。
PUT /api/bots/commands	替换全局命令列表。
PUT /api/bots/guilds/:guildId/commands	替换该社区的命令列表。
POST /api/bots/voice/join	加入语音：{channel_id}。
POST /api/bots/voice/leave	离开语音：{channel_id}；返回 204。

POST /api/bots/messages
{
  "channel_id": 42,
  "content": "来自机器人的问候！",
  "reply_to_id": 123
}

发送成功时返回 201 { message }。没有请求体时不要设置 Content-Type: application/json：空的 JSON 请求可能返回 400。

管理机器人与权限

账户令牌	操作
GET /api/bots；POST /api/bots	列出你的机器人；使用用户名和可选资料字段创建。
PATCH /api/bots/:id；DELETE /api/bots/:id	编辑资料；删除机器人及其消息。
GET /api/bots/:id/tokens；POST /api/bots/:id/tokens	查看令牌信息；使用 {name} 签发新令牌。
DELETE /api/bots/:id/tokens/:tokenId	撤销令牌。
POST /api/guilds/:guildId/bots	添加 {bot_id}。
DELETE /api/guilds/:guildId/bots/:botId	从社区中移除。
GET /api/guilds/:guildId/bots/:botId/permissions	当前权限位掩码与可用权限。
PUT /api/guilds/:guildId/bots/:botId/permissions	保存 {permissions: "114688"}；bigint 以字符串形式发送。

机器人在每个社区拥有独立的权限位掩码，而不是普通的成员角色。查看频道：16384；发送消息：32768；语音：65536。这三项相加为 114688。机器人不会获得管理员权限。

斜杠命令

PUT /api/bots/commands
{ "commands": [
  { "name": "ping", "description": "Check the bot response", "options": [] },
  { "name": "echo", "description": "Repeat text", "options": [
    { "name": "text", "description": "Your text", "type": "string", "required": true }
  ] }
] }

名称：1–32 个字符，可用 a-z0-9_-。最多 100 个命令，每个命令最多 10 个选项。类型：string、number、boolean、user、channel、role；最多 25 个 choices。命令描述最多 200 个字符。

PUT 会替换整个列表，因此请始终发送完整的命令集合。在 message:create 中，被识别的调用会包含 command: {bot_id, name, options, args}。请检查 bot_id，避免响应其他机器人的命令。已禁用或不存在的命令会以普通文本形式送达。

选择成员、频道或角色

user、channel 和 role 类型的选项不使用手动输入，而是从可搜索的列表中选择。机器人收到的是提及标记而不是名称，因此重命名频道、角色或成员都不会破坏已经发出的调用。

类型	提供的内容	机器人收到的内容
user	执行该命令的社区中的成员	<@id>
channel	该社区的文本频道和语音频道	<#id>
role	该社区的角色	<@&id>

搜索会匹配名称，对成员还会匹配昵称和登录名。
服务词同样可用：“voice”匹配语音频道，“role”匹配角色，“text”匹配文本频道。
名称开头的匹配项会排在前面。
最多显示八个选项；如果没有你想要的，请细化搜索词。
回车选择第一项，方向键移动选择，Esc 清空搜索，退格键返回普通输入。

该值会以标记形式出现在 command.options（例如 { "user": "<@42>" }）中，并在 command.args 的相同位置出现。直接使用纯 ID 也被接受，但只有标记才会在回复文本中渲染为提及。

网关与事件

wss://api.example.org/api/bots/gateway?token=<BOT_TOKEN>

{ "type": "ready", "bot_id": 7, "guilds": [1, 2] }
{ "type": "ping" }
{ "type": "pong" }

事件：message:create、message:update、message:delete、reaction:add、reaction:remove、interaction。动作事件的数据位于 data；ready 的顶层带有 bot_id 和 guilds。

每个连接的队列最多缓存 256 条消息。溢出时会发送 message:drop，较早的事件可能丢失。请实现带延迟的重连、pong 监控以及通过 REST 恢复状态。不要假设消息只会送达一次。

按钮、嵌入内容与交互

{
  "channel_id": 42,
  "embeds": [{ "title": "测试", "description": "请按下按钮", "color": 5793266 }],
  "components": [{ "type": 1, "components": [
    { "custom_id": "ping", "label": "Ping", "style": 1 }
  ] }]
}

按钮标签最多 80 个字符，custom_id 必须唯一且不超过 100 个字符。链接按钮使用 http/https 网址代替 custom_id。最多 5 行、每行 5 个按钮，共 25 个。样式 1–4：primary、secondary、success、danger。支持 disabled 和 emoji。

{ "type": "interaction-reply", "nonce": "from the event",
  "action": "ephemeral", "content": "Pong！" }

请在 3 秒内响应。ephemeral 仅点击者可见；message 会发布到频道；update 会编辑带按钮的那条消息。临时响应在内存中最多保留 15 分钟，重启后消失，并不是秘密存储。

content：最多 2000 个字符；最多 10 个嵌入内容，合计 6000 个字符。自定义表情：<:name:id>。嵌入内容的示例也可参见Webhook。

语音

POST /api/bots/voice/join 会返回 channel_id、identity 和 livekit。如果配置了 LiveKit，请使用返回的 token 和 livekitUrl 配合兼容的客户端 SDK。当 livekit: null 时，机器人只出现在成员列表中，不传输音频。REST 请求本身不会开始播放。

错误与运维

情况	如何处理
400	检查字段类型、长度、JSON 以及组件的格式。
401	检查主机和令牌。令牌被撤销时，请换发新令牌后再重试。
403	检查机器人的成员身份及其在该频道或社区中的权限。
404	检查 API 地址和本地资源标识。
429	如果响应包含 Retry-After 就按其等待，并加大延迟。
断线 / 5xx	使用有上限的退避重连。不要盲目重发：可能出现重复消息。

请在日志中隐藏密钥，限制环境变量的访问，并且不要响应机器人自己发送的消息。请与管理员和用户协商数据收集方式，并明确保留与删除策略。

机器人的语音频道

拥有独立 CREATE_VOICE_CHANNELS 权限的机器人可以通过 POST /api/bots/guilds/:guildId/channels 创建语音频道。状态查询：GET /api/bots/guilds/:guildId/voice-states。请求移动：POST /api/bots/guilds/:guildId/voice/move。删除空频道：DELETE /api/bots/channels/:channelId。主机会检查权限和限制，仅持有令牌并不授予这些操作权限。