322 lines
8.9 KiB
Markdown
322 lines
8.9 KiB
Markdown
# 消息模板
|
||
|
||
消息模板功能允许您创建可复用的消息模板，通过占位符实现动态内容替换，提高消息发送的灵活性和效率。
|
||
|
||
::: tip ⭐ 作者推荐
|
||
消息模板是 Message Nest 的核心功能，也是我们**强烈推荐**的使用方式。相比传统的任务发送（V1 API），模板方式具有以下显著优势：
|
||
|
||
**为什么推荐使用模板？**
|
||
1. **开发效率提升 3 倍** - 一次定义模板，所有项目复用，无需重复编写消息内容
|
||
2. **维护成本降低 80%** - 修改消息格式只需在后台更新模板，无需修改代码、重新部署
|
||
3. **团队协作更顺畅** - 开发负责 API 集成，运营负责内容维护，职责清晰
|
||
4. **灰度发布更安全** - 支持模板启用/禁用，可以随时回滚，降低风险
|
||
5. **内容管理更规范** - 所有消息模板集中管理，便于审核和统一风格
|
||
|
||
**适用场景：**
|
||
- ✅ 用户通知（注册、登录、密码重置等）
|
||
- ✅ 订单消息（下单、支付、发货、退款等）
|
||
- ✅ 系统告警（服务异常、资源不足等）
|
||
- ✅ 营销推广（活动通知、优惠券等）
|
||
- ✅ 完全动态的内容（通过占位符实现，如 `{{content}}`）
|
||
- ✅ **所有消息发送场景**
|
||
|
||
::: info 关于完全动态内容
|
||
即使消息内容完全动态，也推荐使用模板方式。你可以创建一个只包含一个占位符的模板，如：
|
||
|
||
**模板内容：** `{{content}}`
|
||
|
||
**API 调用：**
|
||
```json
|
||
{
|
||
"placeholders": {
|
||
"content": "这里是完全动态的内容"
|
||
}
|
||
}
|
||
```
|
||
|
||
这样做的好处是：
|
||
1. 后期如果需要添加固定格式（如标题、签名），只需修改模板，无需改代码
|
||
2. 所有消息统一管理，便于审计和监控
|
||
3. 可以随时启用/禁用，便于灰度发布
|
||
|
||
**V1 API（任务）的定位：**
|
||
- 仅为兼容历史数据而保留
|
||
- 不推荐在任何新项目中使用
|
||
- 后续维护重点在模板功能上
|
||
:::
|
||
|
||
|
||
## 功能特性
|
||
|
||
- ✅ **多格式支持** - 支持 Text、HTML、Markdown 三种格式
|
||
- ✅ **占位符替换** - 使用 `{{key}}` 语法定义动态内容
|
||
- ✅ **实例配置** - 为模板配置多个发送实例（渠道）
|
||
- ✅ **@提醒功能** - 支持钉钉、企业微信的@提醒
|
||
- ✅ **状态管理** - 启用/禁用模板控制
|
||
- ✅ **API调用** - 通过 V2 API 使用模板发送消息
|
||
|
||
## 创建模板
|
||
|
||
### 1. 基本信息
|
||
|
||
在管理后台的"消息模板"页面，点击"新建模板"按钮：
|
||
|
||
- **模板名称** - 模板的唯一标识名称
|
||
- **模板描述** - 模板的用途说明（可选）
|
||
- **状态** - 启用/禁用
|
||
|
||
### 2. 定义占位符
|
||
|
||
占位符用于在发送消息时动态替换内容。
|
||
|
||
**添加占位符：**
|
||
|
||
| 字段 | 说明 | 示例 |
|
||
|------|------|------|
|
||
| Key | 占位符键名 | `username` |
|
||
| Label | 显示标签 | `用户名` |
|
||
| Default | 默认值（可选） | `Guest` |
|
||
|
||
**使用示例：**
|
||
|
||
```json
|
||
[
|
||
{
|
||
"key": "username",
|
||
"label": "用户名",
|
||
"default": "Guest"
|
||
},
|
||
{
|
||
"key": "email",
|
||
"label": "邮箱地址",
|
||
"default": "user@example.com"
|
||
},
|
||
{
|
||
"key": "action",
|
||
"label": "操作类型",
|
||
"default": "登录"
|
||
}
|
||
]
|
||
```
|
||
|
||
### 3. 编写模板内容
|
||
|
||
支持三种格式，可以根据需要填写一种或多种：
|
||
|
||
#### Text 模板
|
||
|
||
纯文本格式，适用于所有渠道：
|
||
|
||
```text
|
||
您好，{{username}}！
|
||
|
||
您的账号 {{email}} 刚刚进行了 {{action}} 操作。
|
||
|
||
如果这不是您本人的操作，请立即联系我们。
|
||
```
|
||
|
||
#### HTML 模板
|
||
|
||
HTML 格式，适用于邮件等支持富文本的渠道：
|
||
|
||
```html
|
||
<div style="font-family: Arial, sans-serif;">
|
||
<h2>您好，{{username}}！</h2>
|
||
<p>您的账号 <strong>{{email}}</strong> 刚刚进行了 <span style="color: #007bff;">{{action}}</span> 操作。</p>
|
||
<p style="color: #dc3545;">如果这不是您本人的操作，请立即联系我们。</p>
|
||
</div>
|
||
```
|
||
|
||
#### Markdown 模板
|
||
|
||
Markdown 格式，适用于钉钉、企业微信等支持 Markdown 的渠道：
|
||
|
||
```markdown
|
||
## 您好，{{username}}！
|
||
|
||
您的账号 **{{email}}** 刚刚进行了 `{{action}}` 操作。
|
||
|
||
> ⚠️ 如果这不是您本人的操作，请立即联系我们。
|
||
```
|
||
|
||
### 4. 配置 @提醒（可选）
|
||
|
||
针对钉钉、企业微信等渠道，可以配置@提醒：
|
||
|
||
- **@手机号** - 多个手机号用逗号分隔，如：`13800138000,13900139000`
|
||
- **@用户ID** - 多个用户ID用逗号分隔
|
||
- **@所有人** - 勾选后会@所有群成员
|
||
|
||
::: warning 注意
|
||
@提醒功能仅在支持的渠道（钉钉、企业微信）中生效。
|
||
:::
|
||
|
||
## 配置发送实例
|
||
|
||
创建模板后，需要为模板配置发送实例（渠道）。
|
||
|
||
### 1. 添加实例
|
||
|
||
在模板列表中，点击"实例"按钮：
|
||
|
||
1. 选择发送渠道（从已创建的渠道中选择）
|
||
2. 配置实例参数（如邮箱收件人地址）
|
||
3. 选择消息格式（Text/HTML/Markdown）
|
||
4. 保存实例
|
||
|
||
### 2. 实例配置说明
|
||
|
||
不同渠道需要配置不同的参数：
|
||
|
||
**邮件渠道：**
|
||
- **固定模式**：
|
||
- 收件人邮箱地址
|
||
- 消息格式：Text 或 HTML
|
||
- **动态接收者模式（群发）** 🆕：
|
||
- 勾选"动态接收者模式"
|
||
- 无需配置固定收件人
|
||
- 发送时通过 API 的 `recipients` 参数指定多个收件人
|
||
- 适用于邮件群发场景
|
||
|
||
**钉钉/企业微信：**
|
||
- 消息格式：Text 或 Markdown
|
||
|
||
**微信公众号：**
|
||
- **固定模式**：
|
||
- 用户 OpenID
|
||
- **动态接收者模式（群发）** 🆕：
|
||
- 勾选"动态接收者模式"
|
||
- 无需配置固定 OpenID
|
||
- 发送时通过 API 的 `recipients` 参数指定多个 OpenID
|
||
|
||
**自定义 Webhook：**
|
||
- 根据 Webhook 要求配置
|
||
|
||
::: warning 动态接收者模式限制
|
||
1. 一个模板只能配置一个动态接收实例
|
||
2. 动态接收实例不能与固定接收实例混合使用
|
||
3. 如果配置了动态接收实例，API 调用时 `recipients` 参数为必填
|
||
4. 建议控制接收者数量，避免触发渠道限流
|
||
:::
|
||
|
||
### 3. 管理实例
|
||
|
||
- **启用/禁用** - 控制实例是否参与发送
|
||
- **编辑** - 修改实例配置
|
||
- **删除** - 删除不需要的实例
|
||
|
||
## 预览模板
|
||
|
||
在编辑模板时，可以使用"预览"功能查看替换占位符后的效果：
|
||
|
||
1. 点击"预览"按钮
|
||
2. 填写占位符的测试值
|
||
3. 查看 Text/HTML/Markdown 三种格式的渲染效果
|
||
|
||
## 使用模板发送消息
|
||
|
||
### 通过 API 调用
|
||
|
||
使用 V2 API 发送模板消息，详见 [V2 API 文档](/api/v2)。
|
||
|
||
**基本流程：**
|
||
|
||
1. 获取模板 Token（在模板详情页查看）
|
||
2. 准备占位符数据
|
||
3. 调用 V2 API 发送
|
||
|
||
**示例：**
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/api/v2/message/send \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"token": "encrypted_template_token",
|
||
"title": "账号安全提醒",
|
||
"placeholders": {
|
||
"username": "张三",
|
||
"email": "zhangsan@example.com",
|
||
"action": "登录"
|
||
}
|
||
}'
|
||
```
|
||
|
||
**动态接收者示例（群发）** 🆕：
|
||
|
||
```bash
|
||
curl -X POST http://your-domain/api/v2/message/send \
|
||
-H "Content-Type: application/json" \
|
||
-d '{
|
||
"token": "encrypted_template_token",
|
||
"title": "活动通知",
|
||
"placeholders": {
|
||
"activity_name": "双十二大促",
|
||
"discount": "全场8折"
|
||
},
|
||
"recipients": [
|
||
"user1@example.com",
|
||
"user2@example.com",
|
||
"user3@example.com"
|
||
]
|
||
}'
|
||
```
|
||
|
||
## 最佳实践
|
||
|
||
### 1. 占位符命名
|
||
|
||
- 使用有意义的英文名称，如 `username`、`order_id`
|
||
- 避免使用特殊字符，建议使用下划线分隔
|
||
- 保持命名一致性
|
||
|
||
### 2. 模板设计
|
||
|
||
- **简洁明了** - 模板内容应简洁清晰
|
||
- **格式适配** - 根据渠道特性选择合适的格式
|
||
- **默认值** - 为占位符设置合理的默认值
|
||
- **测试验证** - 使用预览功能验证模板效果
|
||
|
||
### 3. 实例管理
|
||
|
||
- **合理分组** - 为不同用途创建不同的模板
|
||
- **渠道选择** - 根据消息类型选择合适的渠道
|
||
- **定期检查** - 定期检查实例配置的有效性
|
||
|
||
### 4. 安全性
|
||
|
||
- **Token 保护** - 妥善保管模板 Token
|
||
- **权限控制** - 合理设置模板的启用/禁用状态
|
||
- **内容审查** - 注意模板内容的合规性
|
||
|
||
## 常见问题
|
||
|
||
### Q: 占位符没有被替换？
|
||
|
||
**A:** 检查以下几点：
|
||
- 占位符格式是否正确（`{{key}}`）
|
||
- API 调用时是否传递了对应的 placeholders 参数
|
||
- Key 名称是否匹配
|
||
|
||
### Q: 如何选择消息格式？
|
||
|
||
**A:** 根据渠道特性选择：
|
||
- **邮件** - 推荐使用 HTML 格式，视觉效果更好
|
||
- **钉钉/企业微信** - 推荐使用 Markdown 格式，支持富文本
|
||
- **其他渠道** - 使用 Text 格式，兼容性最好
|
||
|
||
### Q: 可以为一个模板配置多个实例吗？
|
||
|
||
**A:** 可以。一个模板可以配置多个发送实例，调用 API 时会自动遍历所有启用的实例进行发送。
|
||
|
||
### Q: @提醒不生效？
|
||
|
||
**A:** 确认以下几点：
|
||
- 渠道是否支持@提醒（仅钉钉、企业微信支持）
|
||
- 手机号或用户ID格式是否正确
|
||
- 机器人是否有@权限
|
||
|
||
## 下一步
|
||
|
||
- 查看 [V2 API 文档](/api/v2) 了解如何通过 API 使用模板
|
||
- 查看 [API 示例](/api/examples) 了解各语言的调用方式
|