mirror of
https://github.com/kuaifan/dootask.git
synced 2026-07-31 18:35:56 +00:00
65 lines
2.3 KiB
Markdown
65 lines
2.3 KiB
Markdown
---
|
||
id: bot.webhook.concept
|
||
title: 机器人 Webhook 接入
|
||
type: concept
|
||
feature: bot
|
||
scope: end-user
|
||
locale: zh
|
||
aliases:
|
||
- webhook
|
||
- 机器人回调
|
||
- 外部系统接入机器人
|
||
- 机器人事件订阅
|
||
- 怎么让机器人自动回复
|
||
- bot 推送地址
|
||
related_tools: []
|
||
related_pages: [application]
|
||
prerequisites:
|
||
- 已创建用户机器人（[[bot.create.howto]]）
|
||
negative:
|
||
- webhook_url 必须以 `http://` 或 `https://` 开头，否则不发送
|
||
- URL 长度最大 255 字符
|
||
- 调用超时 30 秒，超时不重试
|
||
- 用户自建机器人收到斜杠开头（`/...`）的消息直接忽略，不会触发 webhook
|
||
last_verified: v1.7.90
|
||
---
|
||
|
||
# 机器人 Webhook 接入
|
||
|
||
## 定义
|
||
Webhook 是把「机器人收到的事件」用 HTTP POST 推到外部服务的地址。外部服务回 `{"code":200,"message":"..."}` 时，DooTask 会把 `message` 作为机器人的文本回复发回会话。
|
||
|
||
## 可订阅事件
|
||
后端常量见 `App\Models\UserBot`：
|
||
|
||
| 事件 key | 触发时机 |
|
||
|---|---|
|
||
| `message` | 机器人收到消息（单聊任意消息；群聊需 @ 机器人） |
|
||
| `dialog_open` | 用户首次打开和机器人的会话 |
|
||
| `member_join` | 群聊里机器人或他人加入 |
|
||
| `member_leave` | 群聊里成员离开 |
|
||
|
||
不勾任何事件时默认按 `[message]` 处理（参考 `normalizeWebhookEvents`）。
|
||
|
||
## 请求体字段
|
||
`event = message` 时主要字段：
|
||
|
||
- `event`: `message`
|
||
- `text`: 用户的纯文本指令
|
||
- `reply_text`: 若是引用回复，被引用消息的文本
|
||
- `token`: 机器人当次有效的 API token，可调 DooTask API 代发消息
|
||
- `dialog_id` / `dialog_type` / `session_id`
|
||
- `msg_id` / `msg_uid` / `mention`（是否被 @）
|
||
- `bot_uid`: 机器人 userid
|
||
- `msg_user`: 发送方信息（userid / email / nickname / 临时 token）
|
||
- `extras`: JSON 字符串，含 `timestamp` 等
|
||
- `version`: 当前 DooTask 版本
|
||
|
||
## 设置
|
||
在「我的机器人」编辑面板填 `webhook_url` 并勾事件；或单聊「机器人管理」里 `/webhook <bot_id> <url>`。
|
||
|
||
## 不支持
|
||
- 不支持鉴权签名（如 HMAC），请用 HTTPS + 服务端校验 `token`
|
||
- 不支持调用失败重试 / 死信队列；失败仅在后端 info 日志记录
|
||
- 不能区分 webhook 收到的消息是来自哪个具体群成员之外的额外字段
|