消息模板

消息模板功能允许您创建可复用的消息模板，通过占位符实现动态内容替换，提高消息发送的灵活性和效率。

⭐ 作者推荐

消息模板是 Message Nest 的核心功能，也是我们强烈推荐的使用方式。相比传统的任务发送（V1 API），模板方式具有以下显著优势：

为什么推荐使用模板？

开发效率提升 3 倍 - 一次定义模板，所有项目复用，无需重复编写消息内容
维护成本降低 80% - 修改消息格式只需在后台更新模板，无需修改代码、重新部署
团队协作更顺畅 - 开发负责 API 集成，运营负责内容维护，职责清晰
灰度发布更安全 - 支持模板启用/禁用，可以随时回滚，降低风险
内容管理更规范 - 所有消息模板集中管理，便于审核和统一风格

适用场景：

✅ 用户通知（注册、登录、密码重置等）
✅ 订单消息（下单、支付、发货、退款等）
✅ 系统告警（服务异常、资源不足等）
✅ 营销推广（活动通知、优惠券等）
✅ 完全动态的内容（通过占位符实现，如）
✅ 所有消息发送场景

关于完全动态内容

即使消息内容完全动态，也推荐使用模板方式。你可以创建一个只包含一个占位符的模板，如：

模板内容：

API 调用：

json

{
  "placeholders": {
    "content": "这里是完全动态的内容"
  }
}

这样做的好处是：

后期如果需要添加固定格式（如标题、签名），只需修改模板，无需改代码
所有消息统一管理，便于审计和监控
可以随时启用/禁用，便于灰度发布

V1 API（任务）的定位：

仅为兼容历史数据而保留
不推荐在任何新项目中使用
后续维护重点在模板功能上

功能特性

✅ 多格式支持 - 支持 Text、HTML、Markdown 三种格式
✅ 占位符替换 - 使用语法定义动态内容
✅ 实例配置 - 为模板配置多个发送实例（渠道）
✅ @提醒功能 - 支持钉钉、企业微信的@提醒
✅ 状态管理 - 启用/禁用模板控制
✅ 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用逗号分隔
@所有人 - 勾选后会@所有群成员

注意

@提醒功能仅在支持的渠道（钉钉、企业微信）中生效。

配置发送实例

创建模板后，需要为模板配置发送实例（渠道）。

1. 添加实例

在模板列表中，点击"实例"按钮：

选择发送渠道（从已创建的渠道中选择）
配置实例参数（如邮箱收件人地址）
选择消息格式（Text/HTML/Markdown）
保存实例

2. 实例配置说明

不同渠道需要配置不同的参数：

邮件渠道：

固定模式：
- 收件人邮箱地址
- 消息格式：Text 或 HTML
动态接收者模式（群发） 🆕：
- 勾选"动态接收者模式"
- 无需配置固定收件人
- 发送时通过 API 的 recipients 参数指定多个收件人
- 适用于邮件群发场景

钉钉/企业微信：

消息格式：Text 或 Markdown

微信公众号：

固定模式：
- 用户 OpenID
动态接收者模式（群发） 🆕：
- 勾选"动态接收者模式"
- 无需配置固定 OpenID
- 发送时通过 API 的 recipients 参数指定多个 OpenID

自定义 Webhook：

根据 Webhook 要求配置

动态接收者模式限制

一个模板只能配置一个动态接收实例
动态接收实例不能与固定接收实例混合使用
如果配置了动态接收实例，API 调用时 recipients 参数为必填
建议控制接收者数量，避免触发渠道限流

3. 管理实例

启用/禁用 - 控制实例是否参与发送
编辑 - 修改实例配置
删除 - 删除不需要的实例

预览模板

在编辑模板时，可以使用"预览"功能查看替换占位符后的效果：

点击"预览"按钮
填写占位符的测试值
查看 Text/HTML/Markdown 三种格式的渲染效果

使用模板发送消息

通过 API 调用

使用 V2 API 发送模板消息，详见 V2 API 文档。

基本流程：

获取模板 Token（在模板详情页查看）
准备占位符数据
调用 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: 检查以下几点：

占位符格式是否正确（）
API 调用时是否传递了对应的 placeholders 参数
Key 名称是否匹配

Q: 如何选择消息格式？

A: 根据渠道特性选择：

邮件 - 推荐使用 HTML 格式，视觉效果更好
钉钉/企业微信 - 推荐使用 Markdown 格式，支持富文本
其他渠道 - 使用 Text 格式，兼容性最好

Q: 可以为一个模板配置多个实例吗？

A: 可以。一个模板可以配置多个发送实例，调用 API 时会自动遍历所有启用的实例进行发送。

Q: @提醒不生效？

A: 确认以下几点：

渠道是否支持@提醒（仅钉钉、企业微信支持）
手机号或用户ID格式是否正确
机器人是否有@权限

下一步

查看 V2 API 文档了解如何通过 API 使用模板
查看 API 示例了解各语言的调用方式

消息模板 ​

功能特性 ​

创建模板 ​

1. 基本信息 ​

2. 定义占位符 ​

3. 编写模板内容 ​

Text 模板 ​

HTML 模板 ​

Markdown 模板 ​

4. 配置 @提醒（可选） ​

配置发送实例 ​

1. 添加实例 ​

2. 实例配置说明 ​

3. 管理实例 ​

预览模板 ​

使用模板发送消息 ​

通过 API 调用 ​

最佳实践 ​

1. 占位符命名 ​

2. 模板设计 ​

3. 实例管理 ​

4. 安全性 ​

常见问题 ​

Q: 占位符没有被替换？ ​

Q: 如何选择消息格式？ ​

Q: 可以为一个模板配置多个实例吗？ ​

Q: @提醒不生效？ ​

下一步 ​