自定义 API 指令
把你自己的 HTTP 接口包装成机器人指令:群成员发指令 → 平台请求你的接口 → 按模板渲染结果回复。适合接自己的服务(签到系统、库存查询、游戏面板等)。
配置入口
控制台「机器人功能 → 自定义 API」面板添加,每个接口一条配置:
| 字段 | 说明 |
|---|---|
| 指令 | 触发词,如 天气 |
| 匹配模式 | 精确 / 前缀 / 正则 |
| 生效范围 | 全部 / 仅群聊 / 仅私聊 |
| 接口地址 + 方法 | GET / POST,支持请求头和请求体 |
| 回复类型 | 文本 / Markdown |
| 回复模板 | 渲染规则见下 |
| 按钮 | 可附加 QQ 原生按钮 |
模板渲染
假设接口返回:
json
{ "city": "太原", "temp": 12, "list": [{ "name": "a", "v": 1 }, { "name": "b", "v": 2 }] }模板写法:
text
## {city} 当前 {temp}℃
{#each json.list}{index}. {name} = {v}
{/each}| 写法 | 输出 |
|---|---|
{result} | 原始响应文本 |
{json.temp} | JSON 字段(按点号取路径) |
{#each json.list}…{/each} | 遍历数组,行内用 {index}(从 1 开始)和字段名 |
| 嵌套字段 | {json.user.name} 同理 |
- 取不到的字段渲染为空串,不会报错
- 数字/对象等非字符串值会序列化成 JSON 文本
按钮回调
模板里可以带按钮(写法见内联按钮)。按钮的指令命中某个 API 的触发词或回调数据时,会重新执行该接口,适合做「下一页」刷新数据。
安全限制
- 接口地址必须是公网可达的目标(平台内网地址会被拦截)
- 不要把内部管理接口、带管理凭据的接口直接暴露成群指令——群里任何人都能触发
- 响应过大或超时会有上限保护,报错信息会回显到群
