247 lines
15 KiB
Markdown
247 lines
15 KiB
Markdown
# 发送微信消息使用说明
|
||
|
||
文档类型：模块 API 事实页
|
||
是否可直接用于生成代码：是，但 `userid`、`username`、模板标题、模板关键字含义和真实通知内容必须来自用户需求或项目上下文
|
||
遇到不确定时：[index.md](index.md)、调用侧账户体系文档、项目实际接口说明、天软科技服务号模板列表
|
||
|
||
本页整理通过“天软科技服务号”发送微信模板消息的接口事实。它负责告诉智能体“该调用哪个函数、参数顺序是什么、同步和异步怎么选择、状态如何查询”，不负责替用户创造账户、授权关系、模板映射或通知内容。
|
||
|
||
## 智能体微信消息决策规则
|
||
|
||
- 用户要“发送微信通知 / 微信消息 / 微信告警 / 微信模板消息 / 查询微信发送状态”时，优先使用本页。
|
||
- 紧急通知、需要立刻知道发送结果时，默认使用 `send_wechat_message(...)`。
|
||
- 非紧急通知、批量通知、发送后可稍后查询状态时，默认使用 `send_wechat_message_async(...)`。
|
||
- 用户要求查询异步状态时，生成 `get_wechat_message_status(userid, username, wechat_message_id)`；三个实参必须来自参数、已知变量或项目上下文。
|
||
- 参数必须严格按接口顺序传入；所有参数按字符串处理。
|
||
- `url` 是固定位置参数；无详情地址时传空字符串 `""`。
|
||
- `k1` 到 `k6` 的含义由模板标题决定；只按模板映射或用户输入填充，不要发明关键字含义。
|
||
- 用户要求“通知第一眼看到”的内容时，放入带字段名的 `kN` 参数；`first` 和 `remark` 只作为点入通知后的详情文本。
|
||
- 给他人发消息时，必须使用接收者授权给发送者的 `userid`，不要把发送者自己的 `userid` 当成接收者标识。
|
||
- 不要发明 `userid`、`username`、项目封装函数、模板标题、模板关键字、授权关系或账号映射。
|
||
|
||
## 前置条件
|
||
|
||
| 条件 | 说明 |
|
||
| ------------------------------- | -------------------------------------------------------------------------------------- |
|
||
| 已绑定服务号 | 首次使用需要关注并绑定“天软科技服务号”，绑定后取得 `userid` |
|
||
| 已取得 `userid` | `userid` 与用户账户和微信绑定关系相关，应由调用侧提供 |
|
||
| 给他人发送时已授权 | 接收者绑定后在服务号 `userid` 页面授权发送者账号，发送者使用接收者提供的 `userid` 发送 |
|
||
| 查询异步状态时已取得 `username` | `username` 是账号名，脚本查询发送状态时需要；来源以项目账户体系为准 |
|
||
|
||
## 接口总览
|
||
|
||
| 函数 | 用途 | 返回值 |
|
||
| ---------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------------- |
|
||
| `send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])` | 同步发送模板消息 | 成功返回字符串 `success`；失败返回错误信息 |
|
||
| `send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])` | 异步发送模板消息 | 返回 16 位字符串消息 ID |
|
||
| `get_wechat_message_status(userid, username, wechat_message_id)` | 查询异步发送结果 | 成功返回字符串 `成功`；否则返回状态信息或错误信息 |
|
||
|
||
## 同步发送
|
||
|
||
签名：
|
||
|
||
```text
|
||
send_wechat_message(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])
|
||
```
|
||
|
||
参数表：
|
||
|
||
| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
|
||
| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- |
|
||
| 1 | `userid` | 是 | 字符串 | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` |
|
||
| 2 | `url` | 是 | 字符串 | 详情地址；没有详情地址时传 `""` |
|
||
| 3 | `title` | 是 | 字符串 | 模板消息标题，例如 `监控报告通知` |
|
||
| 4 | `first` | 是 | 字符串 | 详情页开头文本；不作为通知列表首屏字段 |
|
||
| 5 | `remark` | 是 | 字符串 | 详情页结尾备注；不作为通知列表首屏字段 |
|
||
| 6 | `k1` | 条件必填 | 字符串 | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段 |
|
||
| 7 | `k2` | 条件必填 | 字符串 | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段 |
|
||
| 8 | `k3` | 否 | 字符串 | 模板关键字 3；部分模板需要 |
|
||
| 9 | `k4` | 否 | 字符串 | 模板关键字 4；部分模板需要 |
|
||
| 10 | `k5` | 否 | 字符串 | 模板关键字 5；部分模板需要 |
|
||
| 11 | `k6` | 否 | 字符串 | 模板关键字 6；部分模板需要 |
|
||
|
||
返回值：
|
||
|
||
| 返回值 | 含义 |
|
||
| ---------- | ------------ |
|
||
| `success` | 同步发送成功 |
|
||
| 其他字符串 | 错误信息 |
|
||
|
||
使用规则：
|
||
|
||
- 同步发送会阻塞当前程序，必须等待发送函数执行完毕后才进入下一步。
|
||
- 紧急通知优先使用同步发送。
|
||
- 返回值不是 `success` 时，按错误信息处理。
|
||
|
||
## 异步发送
|
||
|
||
签名：
|
||
|
||
```text
|
||
send_wechat_message_async(userid, url, title, first, remark[, k1, k2, k3, k4, k5, k6])
|
||
```
|
||
|
||
参数表：
|
||
|
||
| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
|
||
| -------- | -------- | -------- | -------- | ----------------------------------------------------------------- |
|
||
| 1 | `userid` | 是 | 字符串 | 绑定账户后取得的用户标识；给他人发送时使用接收者授权后的 `userid` |
|
||
| 2 | `url` | 是 | 字符串 | 详情地址；没有详情地址时传 `""` |
|
||
| 3 | `title` | 是 | 字符串 | 模板消息标题 |
|
||
| 4 | `first` | 是 | 字符串 | 详情页开头文本；不作为通知列表首屏字段 |
|
||
| 5 | `remark` | 是 | 字符串 | 详情页结尾备注；不作为通知列表首屏字段 |
|
||
| 6 | `k1` | 条件必填 | 字符串 | 模板关键字 1；带字段名的 `kN` 行属于首屏展示字段 |
|
||
| 7 | `k2` | 条件必填 | 字符串 | 模板关键字 2；带字段名的 `kN` 行属于首屏展示字段 |
|
||
| 8 | `k3` | 否 | 字符串 | 模板关键字 3；部分模板需要 |
|
||
| 9 | `k4` | 否 | 字符串 | 模板关键字 4；部分模板需要 |
|
||
| 10 | `k5` | 否 | 字符串 | 模板关键字 5；部分模板需要 |
|
||
| 11 | `k6` | 否 | 字符串 | 模板关键字 6；部分模板需要 |
|
||
|
||
返回值：
|
||
|
||
| 返回值 | 含义 |
|
||
| ----------- | ---------------------------------------------------------- |
|
||
| 16 位字符串 | 异步消息 ID；前 10 位为 1900 年以来的秒数，后 6 位为随机数 |
|
||
|
||
使用规则：
|
||
|
||
- 异步发送把命令提交给服务器后立即返回，不等待最终发送结果。
|
||
- 非紧急通知优先使用异步发送。
|
||
- 需要最终结果时，保存返回的 `wechat_message_id`，再调用 `get_wechat_message_status(...)` 查询。
|
||
|
||
## 查询异步发送状态
|
||
|
||
签名：
|
||
|
||
```text
|
||
get_wechat_message_status(userid, username, wechat_message_id)
|
||
```
|
||
|
||
参数表：
|
||
|
||
| 参数位置 | 参数名 | 必填 | 接收类型 | 说明 |
|
||
| -------- | ------------------- | ---- | -------- | ---------------------------------------------------- |
|
||
| 1 | `userid` | 是 | 字符串 | 发送时使用的用户标识 |
|
||
| 2 | `username` | 是 | 字符串 | 账号名；脚本执行查询时需要，来源以项目账户体系为准 |
|
||
| 3 | `wechat_message_id` | 是 | 字符串 | `send_wechat_message_async(...)` 返回的 16 位消息 ID |
|
||
|
||
返回值：
|
||
|
||
| 返回值 | 含义 |
|
||
| ---------- | ------------------ |
|
||
| `成功` | 异步消息发送成功 |
|
||
| 其他字符串 | 状态信息或错误信息 |
|
||
|
||
调用规则：
|
||
|
||
- 状态查询用于异步发送后的结果确认。
|
||
- `username` 按账号名参数、已知变量或项目上下文传入，不写字面量 `"username"`。
|
||
- `wechat_message_id` 使用 `send_wechat_message_async(...)` 的返回值。
|
||
|
||
## 模板展示规则
|
||
|
||
| 模板片段 | 展示位置 | 生成规则 |
|
||
| ----------------------------------- | ---------------------- | ------------------------------------------------ |
|
||
| `字段名：{{kN}}` | 通知列表首屏可见 | 用户要求“第一眼看到”的信息放到对应 `kN` |
|
||
| `{{first}}` | 点入通知后的详情页开头 | 放说明、背景、摘要引导；不承载首屏必须展示的信息 |
|
||
| `{{remark}}` | 点入通知后的详情页结尾 | 放补充说明、处理建议、联系人等尾部信息 |
|
||
| 字面标题行，例如 `监控报告通知` | 模板固定内容 | 不作为接口参数；接口参数 `title` 仍使用模板标题 |
|
||
| 动态标签行，例如 `{{k5}}幅：{{k6}}` | 通知列表首屏可见 | `k5` 填字段标签的一部分，`k6` 填对应数值 |
|
||
|
||
生成规则：
|
||
|
||
- `title` 决定模板，`k1` 到 `k6` 按模板字段名依次填入。
|
||
- 有名称的 `kN` 行是首屏展示字段；需要首屏展示的信息优先放入 `kN`。
|
||
- `first` 和 `remark` 是详情页内容；不要把“第一眼必须看到”的核心字段放入 `first` 或 `remark`。
|
||
- 模板未列出的 `kN` 不主动传入；需要扩展字段时先换模板或由用户提供模板映射。
|
||
|
||
## 模板关键字映射
|
||
|
||
### 系统监控类
|
||
|
||
| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` |
|
||
| -------------------- | ------------ | ------------ | ------------ | ---- | ---- | ---- |
|
||
| `系统运行简报` | 系统名称 | 简报内容 | 发布时间 | | | |
|
||
| `监控报告通知` | 运行状态 | 时间 | | | | |
|
||
| `监控结果通知` | 监控项目 | 内容 | 时间 | | | |
|
||
| `告警通知` | 告警内容 | 告警发生时间 | | | | |
|
||
| `故障恢复通知` | 故障信息 | 恢复时间 | | | | |
|
||
| `服务器异常监控通知` | 监控通知 | 监控通知类型 | 监控通知内容 | | | |
|
||
| `服务器宕机通知` | 故障时间 | 故障原因 | | | | |
|
||
| `服务器恢复通知` | 故障停止时间 | 故障持续时间 | | | | |
|
||
|
||
### 交易通知类
|
||
|
||
| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` |
|
||
| -------------- | -------- | -------- | -------- | -------- | -------- | -------- |
|
||
| `交易成功通知` | 交易金额 | 交易类型 | 交易时间 | 交易单号 | | |
|
||
| `交易完成通知` | 股票简称 | 股票代码 | 股票价格 | 交易状态 | 股票数量 | |
|
||
| `交易下单通知` | 交易品种 | 下单方向 | 下单价格 | 止损价格 | 下单时间 | |
|
||
| `成交回报提示` | 证券名称 | 证券代码 | 买卖标识 | 成交价格 | 成交数量 | 成交时间 |
|
||
| `委托成交提醒` | 数量 | 价格 | 时间 | | | |
|
||
|
||
### 策略通知类
|
||
|
||
| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` |
|
||
| ------------------ | -------- | ---------- | ------------ | ---------- | ------------------------- | ------ |
|
||
| `投资策略更新提醒` | 策略名称 | 操作风格 | 目前策略收益 | | | |
|
||
| `股票调仓通知` | 股票名称 | 操作类型 | 调仓时间 | 调仓价格 | 调仓仓位 | |
|
||
| `实时建仓提醒` | 品种 | 方向 | 仓位 | 价格 | 止盈止损 | |
|
||
| `个股到价通知` | 股票名 | 当前成交价 | 预警价 | | | |
|
||
| `个股涨跌幅通知` | 股票名 | 当前成交价 | 对比日期 | 对比收盘价 | 动态标签，组成 `{{k5}}幅` | 动态值 |
|
||
|
||
### 其他通知类
|
||
|
||
| 模板标题 | `k1` | `k2` | `k3` | `k4` | `k5` | `k6` |
|
||
| ------------------ | -------- | -------- | ---- | ---- | ---- | ---- |
|
||
| `账号绑定成功通知` | 账号名称 | 绑定时间 | | | | |
|
||
| `服务开启通知` | | | | | | |
|
||
| `授权请求通知` | 申请人 | 请求权限 | | | | |
|
||
|
||
`服务开启通知` 当前只记录模板标题，未固定 `k1` 到 `k6` 的字段映射。
|
||
|
||
## 发送示例
|
||
|
||
同步发送系统运行简报：
|
||
|
||
```tsl
|
||
function SendSystemBrief(user_id);
|
||
begin
|
||
url := "";
|
||
title := "系统运行简报";
|
||
first := "系统运行情况如下。";
|
||
k1 := "风控服务";
|
||
k2 := "运行正常";
|
||
dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
|
||
remark := "如有疑问请联系值班人员。";
|
||
|
||
return send_wechat_message(user_id, url, title, first, remark, k1, k2, k3);
|
||
end;
|
||
```
|
||
|
||
异步发送并保留消息 ID：
|
||
|
||
```tsl
|
||
function SendSystemBriefAsync(user_id);
|
||
begin
|
||
url := "";
|
||
title := "系统运行简报";
|
||
first := "系统运行情况如下。";
|
||
k1 := "风控服务";
|
||
k2 := "运行正常";
|
||
dateTimeToString(k3, "YYYY-MM-DD HH:NN:SS", now());
|
||
remark := "如有疑问请联系值班人员。";
|
||
|
||
return send_wechat_message_async(user_id, url, title, first, remark, k1, k2, k3);
|
||
end;
|
||
```
|
||
|
||
查询异步发送结果：
|
||
|
||
```tsl
|
||
function QueryWechatMessageStatus(user_id, username, wechat_message_id);
|
||
begin
|
||
return get_wechat_message_status(user_id, username, wechat_message_id);
|
||
end;
|
||
```
|