模板系统 - 动态通知内容

模板允许您通过在通知标题和正文中加入变量来创建动态、包含丰富上下文的通知。这个强大的功能使个性化和信息性告警能够根据触发数据进行调整，将泛泛的通知转化为可操作的情报。

Echobell 中的模板允许您通过在通知标题和内容中整合变量来创建动态通知。此功能可根据触发数据生成个性化和信息丰富的提醒。

基本模板语法

在 Echobell 模板中，您可以通过将变量包裹在双大括号中来使用它们：

{{变量名}}

当频道被触发时，这些变量将被通过触发器传递的实际值所替代。例如，如果您的标题模板是 您已收到 ${{amount}}，并且您用 amount 值为 100 触发了频道，结果通知将显示为 您已收到 $100。

高级模板表达式

Echobell 模板支持多种表达式，适用于更复杂的场景：

访问对象属性

{{user.name}}
{{user["name"]}}

访问数组元素

{{list[0]}}

使用比较运算符

{{status == "active"}}
{{age > 18}}

逻辑运算符

{{isSubscribed && !isPaused}}
{{isUrgent || isPriory}}

支持所有标准运算符：==、!=、<、>、<=、>=、&&、|| 和 !。

来自不同触发器的模板变量

Webhook 触发器

通过 webhook 触发时，您可以通过以下方式提供变量：

查询字符串参数：

GET https://hook.echobell.one/t/<channel-token>?amount=100&status=active

JSON 主体（用于 POST 请求）：

POST https://hook.echobell.one/t/<channel-token>
Content-Type: application/json

{
  "amount": 100,
  "status": "active",
  "user": {
    "name": "张三",
    "id": 12345
  }
}

特殊变量：
- externalLink：在通知记录中提供可点击链接
- bodyAsText: 如果 Content-Type 是 text/plain，则为请求正文的纯文本内容
- header：提供对 HTTP 请求头的访问（例如，{{header["content-type"]}})

电子邮件触发器

当频道通过电子邮件触发时，以下变量将自动可用：

from：发件人电子邮件地址
to：收件人电子邮件地址
subject：电子邮件主题行
text：电子邮件的纯文本内容
html：电子邮件的 HTML 内容

模板使用案例

比较与布尔值

使用比较或逻辑运算符的表达式会将其布尔结果渲染为文本 true 或 false：

支付超过 $1000：{{amount > 1000}}
高优先级：{{isUrgent || isImportant}}

Echobell 模板不支持内联的 if/else（三元）逻辑。要在不同情况下发送不同内容，请使用频道条件来路由触发，或直接插入原始值。

频道条件

除了在通知内容中使用模板外，您还可以在频道高级设置中设置条件，确定是否应发送通知。这些条件使用相同的表达式语法（不含大括号）。

例如，仅对超过阈值的金额发送通知：

金额 > 100

链接模板

在频道高级设置中配置自定义链接模板，以在通知记录中创建可点击链接：

https://dashboard.example.com/orders/{{orderId}}

如果未设置链接模板，将默认使用 externalLink 变量的值。

系统时间变量（UTC）

这些变量在模板（以及条件）中始终可用，且以 UTC 计算。

以下值直接（扁平）注入，可按名称使用：

year、month（1–12）
dayOfMonth、dayOfWeek（0–6，周日 = 0）
hour（0–23）、minute、second
date（YYYY-MM-DD）、time（HH:mm:ss）
iso：ISO‑8601 时间戳（如 2025-05-06T12:34:56.789Z）

其他值仅在 sys. 命名空间下可用（它们不会作为扁平名称注入）：

sys.timezone：恒为 "UTC"
sys.now：ISO‑8601 时间戳（与 iso 相同的值）
sys.epochMs、sys.epochSeconds：自 Unix 纪元以来的当前时间（数字）
sys.monthName：月份名称（January–December）
sys.dayOfWeekName：星期名称（Sunday–Saturday）

sys. 命名空间也镜像了所有扁平值（例如 sys.year、sys.hour）。

示例：

发送时间 {{date}} {{time}} {{sys.timezone}}
今天是 {{sys.dayOfWeekName}}，{{sys.monthName}} {{dayOfMonth}}，{{year}}
Epoch：{{sys.epochSeconds}}

最佳实践

处理缺失变量：Echobell 没有默认值运算符。|| 运算符纯粹是逻辑运算——它将两侧作为布尔值求值并渲染 true 或 false。因此 {{username || "匿名用户"}} 会渲染字面文本 true 或 false，而绝不会是用户名或回退字符串。当变量缺失时，{{variable}} 只会渲染为空字符串。如果需要保证有值，请在触发负载中显式发送该值，而不要依赖模板回退：
```
用户：{{username}}
服务器：{{serverName}}
检测到的错误：{{errorCount}}
```
信息丰富的模板：在模板中包含关键信息，使通知具有可操作性：
```
{{service}}：{{status}} - {{message}}
```
保持模板简洁：当标题和内容清晰简洁时，通知效果最佳。
测试：使用不同的变量组合测试您的模板，确保它们按预期显示。

模板是创建动态、信息丰富的通知的强大方式，能在用户需要时给他们提供恰到好处的信息。