DooTask「我的机器人」应用使用指南:自建消息机器人的创建、配置与 Webhook 接入
DooTask「我的机器人」应用使用指南:自建消息机器人的创建、配置与 Webhook 接入
「我的机器人」是 DooTask 应用中心内置的 mybot 系统应用,面向所有登录用户提供消息机器人的全生命周期管理:查看、新建、修改、删除自建机器人,并可配置头像、名称、消息保留天数、Webhook URL 与 Webhook 事件订阅。本文将结合前端入口、后端 API 与消息处理任务的源码实现,讲解如何通过「我的机器人」把外部系统接入 DooTask 消息体系,并说明系统机器人与自建机器人之间的权限差异和各类限制。读完本文,你将掌握机器人的创建流程、字段含义、Webhook 事件订阅机制、回调请求体结构,以及通过斜杠指令管理机器人的完整实战方案。
是什么:mybot 系统应用
在 DooTask 应用中心的 11 个固定系统应用中,mybot(我的机器人)卡片对应着自建消息机器人管理入口。系统应用是主程序在应用中心「常用」区硬编码的内置入口,所有登录用户可见(见 resources/ai-kb/zh/concept/apps/system-apps/list.md)。
从后端实现看,「我的机器人」的核心数据由 user_bots 表承载,对应模型 app/Models/UserBot.php。每个自建机器人本质上是一个特殊用户账号(users.bot = 1),它与创建者的归属关系、消息清理天数、Webhook 配置都记录在 user_bots 表中:
| 字段 | 类型 | 说明 |
|---|---|---|
userid |
int | 所属人(创建者)ID |
bot_id |
int | 机器人用户 ID(关联 users.userid) |
clear_day |
int | 消息自动清理天数 |
clear_at |
datetime | 下一次清理时间 |
webhook_url |
string | 消息 Webhook 回调地址 |
webhook_num |
int | Webhook 请求累计次数 |
webhook_events |
array | Webhook 事件订阅配置(JSON 存储) |
机器人账号本身拥有独立的 userid、token、头像和昵称,可以像普通用户一样被加入会话、收发消息、被 @ 触发,但不能登录 UI。它通常用于自动通知、外部系统接入和 AI 对话(见 resources/ai-kb/zh/concept/bot/overview.md)。
入口位置
「我的机器人」在不同终端的入口如下:
- 桌面端:左侧导航「应用」→「我的机器人」卡片
- 移动端:底部 Tabbar「应用」→「我的机器人」
- 进入后,抽屉右上角的「添加机器人」按钮可新建机器人
前端入口实现在 resources/assets/js/pages/manage/application.vue 的应用中心页面中,机器人列表与编辑交互则对应后端 api/users/bot/* 系列接口。
操作步骤
- 打开应用中心,点击「我的机器人」卡片。
- 抽屉内显示当前用户创建的机器人列表;若尚未创建任何机器人,会提示「您没有创建机器人」。
- 对列表中的每条机器人可执行三种操作:
- 开始聊天:打开与该机器人的私聊会话;
- 修改:编辑机器人基本信息和 Webhook 配置;
- 删除:需输入备注原因;系统内置机器人不可删除。
删除动作对应的后端接口是 api/users/bot/delete(bot__delete)。源码位于 app/Http/Controllers/Api/UsersController.php,其校验逻辑依次为:
remark(删除备注)必填,且长度 ≤ 255 字符,否则分别报「请输入删除备注」「删除备注长度限制255个字」;- 目标必须是
users.bot = 1的机器人,否则报「机器人不存在」; - 非本人拥有的机器人,若属于系统机器人(邮箱以
@bot.system结尾)则报「系统机器人不能删除」,否则报「不是你的机器人」; - 校验通过后调用
$botUser->deleteUser($remark)完成删除。
字段说明
「我的机器人」编辑面板中的字段与后端字段一一对应:
| 字段 | 说明 | 后端校验 / 边界 |
|---|---|---|
| 名称 | 机器人昵称 | 2–20 字符,过短或过长都会被拒(报「机器人名称由2-20个字符组成。」,见 UserBot::newBot) |
| 消息保留 | 单位天,默认 90 天 | 取值范围 1–999,超出会被 min(max(intval(...), 1), 999) 钳制(见 bot__edit) |
| Webhook URL | 收到机器人对话消息时回调的地址 | 最长 255 字符,必须 http:// 或 https:// 开头,否则不发送 |
| Webhook 事件 | 勾选要订阅的事件类型 | 仅限内置 4 类事件,不可自定义事件名 |
其中 clear_day(消息保留天数)在源码中体现为 user_bots.clear_day,配合 clear_at 决定定时清理任务何时删除机器人会话中的过期消息。Webhook 事件的合法取值由 UserBot::webhookEventOptions() 返回,其余字符串会被 normalizeWebhookEvents 过滤掉,无法自定义事件名。
名称与会话开关
创建机器人时(对应 api/users/bot/edit 接口且 id 为空),后端调用 UserBot::newBot($userid, $name, $session)。其中:
session参数(0/1)决定是否开启「新会话 / 历史会话」菜单,仅新建时生效,创建后不能更改,需要重建机器人;- 开启
session后,机器人对话窗口会出现新会话、历史会话菜单,且 Webhook 回调消息中会多出session_id字段; - 机器人类型标识为
user-session-*(开启会话)或user-normal-*(普通),与系统机器人的@bot.system邮箱后缀区分。
底层实现:机器人的创建与校验
UserBot::newBot 的实现(app/Models/UserBot.php)揭示了三个关键约束:
- 数量上限:通过
users表关联user_bots表统计该用户拥有的机器人数量,达到 50 个时报「超过最大创建数量」; - 名称校验:名称长度必须在 2–20 字符之间;
- 会话创建:创建成功后自动通过
WebSocketDialog::checkUserDialog建立机器人私聊会话,并发送一条/hello模板消息提示「创建成功」。
编辑操作对应 app/Http/Controllers/Api/UsersController.php 的 bot__edit 方法:管理员可以借此接口修改系统机器人(仅限有限字段),普通用户只能编辑属于自己的机器人,否则返回「不是你的机器人」或「权限不足」。头像字段的更新会经过 Base::unFillUrl 处理并跳过 avatar/ 内置路径,确保头像引用合法。
Webhook 事件订阅与回调机制
Webhook 是把「机器人收到的事件」通过 HTTP POST 推送到外部服务的机制。后端在 UserBot 中定义了 4 个事件常量(app/Models/UserBot.php):
| 事件 key | 触发时机 |
|---|---|
message |
机器人收到消息(单聊任意消息;群聊需 @ 机器人) |
dialog_open |
用户首次打开与机器人的会话 |
member_join |
群聊里机器人或他人加入 |
member_leave |
群聊里成员离开 |
相关规则:
- 不勾选任何事件时,
normalizeWebhookEvents默认按[message]处理; shouldDispatchWebhook会先校验webhook_url非空且以http://或https://开头,再判断事件是否在订阅列表内;dispatchWebhook使用Ihttp::ihttp_post发起 POST 请求,超时 30 秒,超时不重试;请求成功后累加webhook_num计数。失败仅在 info 日志中记录webhook_url、data与error,没有死信队列或重试机制。
消息事件的完整调用链
当机器人收到一条消息时,系统会投递 BotReceiveMsgTask 任务(app/Tasks/BotReceiveMsgTask.php)异步处理,关键流程如下:
- 有效性校验:确认发送者是机器人(
users.bot = 1)、消息存在;若消息本身就是机器人发的则直接忽略——这是为了避免机器人之间互相触发形成死循环; - 指令提取:通过
extractMessageContent()提取文本(含被引用回复的reply_text); - Webhook 推送:调用
handleWebhookRequest处理事件分发; - 会话回复:若为私聊(
dialog->type === 'user'),继续处理签到机器人、匿名机器人等系统逻辑。
对于用户自建机器人,handleWebhookRequest 中有两条重要规则:
- 斜杠指令被忽略:用户自建机器人收到以
/开头(如/help)的消息直接返回,不会触发 Webhook——斜杠指令仅对系统机器人(如bot-manager@bot.system)有效; - 订阅过滤:只有
shouldDispatchWebhook(message)通过(已订阅message事件且 URL 合法)才会推送。
Webhook 回调请求体字段
event = message 时的主要字段如下(见 resources/ai-kb/zh/concept/bot/webhook.md):
| 字段 | 说明 |
|---|---|
event |
固定为 message |
text |
用户的纯文本指令 |
reply_text |
若是引用回复,被引用消息的文本 |
token |
机器人当次有效的 API token,可调用 DooTask API 代发消息 |
dialog_id / dialog_type / session_id |
会话标识;开启 session 的机器人才有 session_id |
msg_id / msg_uid / mention |
消息 ID、发送者用户 ID、是否被 @ |
bot_uid |
机器人 userid |
msg_user |
发送方信息(userid / email / nickname / 临时 token 等) |
extras |
JSON 字符串,含 timestamp 等扩展信息 |
version |
当前 DooTask 版本 |
这些字段在 BotReceiveMsgTask::handleWebhookRequest 中统一组装(app/Tasks/BotReceiveMsgTask.php),其中 token 由 User::generateToken 生成,msg_user.token 是有效期 1 小时的临时 token,外部服务可以凭此调用 API 代机器人回复。
回调响应与自动回复
外部服务收到 POST 后,若返回 JSON {"code":200,"message":"..."},DooTask 会把 message 内容作为机器人的文本回复发回原会话(app/Tasks/BotReceiveMsgTask.php)。这是「外部系统 → 机器人 → 会话」闭环回复的最简实现路径。
需要注意:
- 不支持鉴权签名(如 HMAC),建议使用 HTTPS 并在服务端校验
token字段; - 回调失败不重试、无死信队列,排查问题需查看后端 info 日志。
用斜杠指令管理机器人
除了「我的机器人」面板,还可以在 bot-manager@bot.system(机器人管理)的私聊中通过斜杠指令管理自建机器人(指令处理见 app/Tasks/BotReceiveMsgTask.php):
| 指令 | 作用 |
|---|---|
/list |
列出「我的机器人」(最多 50 条,无则提示「您没有创建机器人。」) |
/newbot 名称 |
创建机器人(名称 2–20 字符) |
/setname <bot_id> <名称> |
修改机器人名称(由机器人管理执行) |
/deletebot <bot_id> |
删除机器人 |
/token <bot_id> |
获取机器人 token |
/revoke <bot_id> |
重置机器人 token(更换 encrypt 与 password) |
/clearday <bot_id> <天数> |
设置保留消息天数(默认取 30,上限 999) |
/webhook <bot_id> <url> |
设置 Webhook 地址(≤ 255 字符,清空则传空字符串) |
/dialog <bot_id> <关键词> |
搜索机器人的会话列表 |
/api |
输出 API 接口文档入口与版本号 |
在机器人自己的单聊里,也可以直接对「自己的机器人」使用这些指令(/list、/newbot 除外,这两项仅限机器人管理)。获取 token 后,外部代码即可凭 token 调用 DooTask API 代机器人发消息。
系统机器人与自建机器人的差异
「我的机器人」列表中可能会出现系统机器人条目,两者权限差异明显:
- 系统机器人:邮箱以
@bot.system结尾,名单写死在UserBot::systemBotName(app/Models/UserBot.php),如「系统消息」「任务提醒」「签到打卡」「会议通知」「审批」以及各 AI 对话机器人。普通用户不能删除(删除会报「系统机器人不能删除」),编辑时会显示「正在修改系统机器人」红色提示,只能修改有限字段,且仅管理员有权限; - 自建机器人:归属创建者本人,可自由修改名称、头像、
clear_day、Webhook 配置,删除需填写备注;创建后不能跨账号转让,也不能把已有普通用户改成机器人。
一个机器人只能绑定一个 Webhook URL;Webhook 事件订阅仅限主程序内置的 message / dialog_open / member_join / member_leave 四类,不可自定义事件名。
限制与边界汇总
综合「我的机器人」面板、创建接口与消息处理任务,自建机器人存在以下边界(可作为开发与排障参考):
- 单个用户最多创建 50 个自建机器人,超出报「超过最大创建数量」;
- 机器人名称 2–20 字符;
clear_day范围 1–999 天,默认 90 天;- Webhook URL 最长 255 字符,必须
http(s)://开头; - Webhook 调用超时 30 秒,失败不重试、无死信队列;
- 用户自建机器人不识别斜杠指令(
/...直接忽略,不触发 Webhook); - 机器人之间不会互相触发(避免死循环);
- 群聊中必须 @ 机器人(或 AI 机器人被 @)才会触发回复;单聊中任意消息都会触发;
- 机器人加入全员群、部门群、项目讨论组通常不被允许(这些群成员由系统自动维护),详见 resources/ai-kb/zh/howto/bot/invite.md。
小结
「我的机器人」(mybot 系统应用)是 DooTask 消息机器人的统一管理入口:创建与编辑走 api/users/bot/edit,删除走 api/users/bot/delete,消息接收与 Webhook 分发由 BotReceiveMsgTask 异步完成,数据层由 app/Models/UserBot.php 承载。理解 user_bots 表的字段含义、4 类 Webhook 事件的触发条件、回调请求体结构与「code:200 + message」响应约定,就能把任意外部系统(监控告警、工单流转、AI 服务等)以最低成本接入 DooTask 的即时消息链路。