Echobell
App Store Google Play

Hệ thống mẫu - Nội dung thông báo linh động

Xây dựng mẫu thông báo linh động với biến, biểu thức và giá trị hệ thống - kèm thực hành tốt nhất để viết cảnh báo rõ ràng.

Mẫu trong Echobell cho phép bạn tạo ra những thông báo linh động, giàu bối cảnh bằng cách đưa biến vào tiêu đề và nội dung thông báo. Tính năng mạnh mẽ này giúp bạn có được các cảnh báo được cá nhân hóa và đầy đủ thông tin, tự thay đổi theo dữ liệu kích hoạt, biến những thông báo chung chung thành thông tin có thể hành động ngay.

Thay vì nhận được một dòng chữ chung chung như "Alert triggered", mẫu cho phép bạn tạo những thông báo cụ thể như "Production server CPU at 95%" hay "Build #142 failed in deploy stage" - cung cấp bối cảnh ngay lập tức mà không cần phải tìm hiểu thêm.

Cú pháp mẫu cơ bản

Trong mẫu của Echobell, bạn có thể dùng biến bằng cách bọc chúng trong cặp ngoặc nhọn kép:

{{variableName}}

Khi một kênh được kích hoạt, những biến này được thay bằng giá trị thật truyền vào lúc kích hoạt. Ví dụ, nếu mẫu tiêu đề của bạn là You have received ${{amount}} và bạn kích hoạt kênh với giá trị amount là 100, thông báo kết quả sẽ hiển thị là You have received $100.

Biểu thức mẫu nâng cao

Mẫu của Echobell hỗ trợ nhiều loại biểu thức cho những tình huống phức tạp hơn:

  • Truy cập thuộc tính của object
{{user.name}}
{{data["value"]}}
  • Truy cập phần tử của mảng
{{items[0]}}
  • Dùng toán tử so sánh
{{status == "active"}}
{{age > 18}}
  • Toán tử logic
{{isSubscribed && !isPaused}}
{{isUrgent || isHighPriority}}

Toàn bộ các toán tử chuẩn đều được hỗ trợ: ==, !=, <, >, <=, >=, &&, || và !.

Biến mẫu từ các cách kích hoạt khác nhau

Kích hoạt bằng Webhook

Khi kích hoạt qua webhook, bạn có thể cung cấp biến bằng cách:

  1. Tham số trong query string:

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

  2. Body JSON (với request POST):

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

{
  "amount": 100,
  "status": "complete",
  "user": {
    "name": "John",
    "id": 12345
  }
}

  3. Biến đặc biệt:

    • externalLink: Tạo một liên kết bấm được trong bản ghi thông báo
    • bodyAsText: Nội dung văn bản thuần của body request nếu Content-Type là text/plain
    • header: Cho phép truy cập các header của HTTP request (ví dụ: {{header["content-type"]}})

Kích hoạt qua Email

Khi một kênh được kích hoạt qua email, những biến sau tự động có sẵn:

  • from: Địa chỉ email của người gửi
  • to: Địa chỉ email của người nhận
  • subject: Tiêu đề email
  • text: Nội dung văn bản thuần của email
  • html: Nội dung HTML của email

Các cách dùng mẫu

So sánh và giá trị boolean

Những biểu thức dùng toán tử so sánh hoặc toán tử logic sẽ kết xuất kết quả boolean của chúng thành chữ true hoặc false:

Payment over $1000: {{amount > 1000}}
High priority: {{isUrgent || isImportant}}

Mẫu của Echobell không hỗ trợ logic if/else nội dòng (toán tử ba ngôi). Để gửi nội dung khác nhau trong những tình huống khác nhau, hãy dùng Điều kiện của kênh để định tuyến các lần kích hoạt, hoặc chèn thẳng giá trị thô vào.

Điều kiện của kênh

Ngoài việc dùng mẫu trong nội dung thông báo, bạn còn có thể đặt Điều kiện trong phần cài đặt nâng cao của kênh để quyết định có gửi thông báo hay không. Những điều kiện này dùng cùng cú pháp biểu thức (nhưng không có cặp ngoặc nhọn).

Ví dụ, để chỉ gửi thông báo với những khoản tiền lớn hơn một ngưỡng nhất định:

amount > 100

Mẫu liên kết

Cấu hình một mẫu liên kết tùy chỉnh trong cài đặt nâng cao của kênh để tạo liên kết bấm được trong bản ghi thông báo:

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

Nếu không đặt mẫu liên kết, hệ thống sẽ mặc định dùng giá trị của biến externalLink.

Biến thời gian hệ thống (UTC)

Những biến này luôn có sẵn cho mẫu (và điều kiện), và được tính theo UTC.

Các giá trị sau được đưa vào trực tiếp (dạng phẳng) và có thể dùng theo tên:

  • year, month (1–12)
  • dayOfMonth, dayOfWeek (0–6, Chủ nhật = 0)
  • hour (0–23), minute, second
  • date (YYYY-MM-DD), time (HH:mm:ss)
  • iso: Dấu thời gian ISO‑8601 (ví dụ: 2025-05-06T12:34:56.789Z)

Những giá trị khác chỉ có trong không gian tên sys. (chúng không được đưa vào dưới dạng tên phẳng):

  • sys.timezone: Luôn là "UTC"
  • sys.now: Dấu thời gian ISO‑8601 (cùng giá trị với iso)
  • sys.epochMs, sys.epochSeconds: Thời gian hiện tại tính từ mốc Unix epoch (dạng số)
  • sys.monthName: Tên tháng (January–December)
  • sys.dayOfWeekName: Tên thứ trong tuần (Sunday–Saturday)

Không gian tên sys. cũng phản chiếu mọi giá trị phẳng (ví dụ sys.year, sys.hour).

Ví dụ:

Sent at {{date}} {{time}} {{sys.timezone}}
Today is {{sys.dayOfWeekName}}, {{sys.monthName}} {{dayOfMonth}}, {{year}}
Epoch: {{sys.epochSeconds}}

Thực hành tốt nhất

Xử lý biến bị thiếu

Echobell không có toán tử giá trị mặc định. Toán tử || thuần túy là toán tử logic — nó đánh giá cả hai vế thành boolean rồi kết xuất ra true hoặc false. Vì vậy {{username || "Anonymous User"}} sẽ hiện đúng chữ true hoặc false, chứ không bao giờ ra tên người dùng hay chuỗi dự phòng.

Khi một biến bị thiếu, {{variable}} chỉ đơn giản được kết xuất thành chuỗi rỗng. Hãy thiết kế nhãn sao cho khi giá trị rỗng thì câu chữ vẫn dễ đọc:

User: {{username}}
Server: {{serverName}}
Errors detected: {{errorCount}}

Nếu bạn cần chắc chắn có giá trị, hãy gửi nó tường minh trong payload kích hoạt thay vì trông cậy vào một giá trị dự phòng trong mẫu.

Mẫu giàu thông tin

Hãy đưa những thông tin then chốt vào mẫu để thông báo có thể hành động được ngay mà không cần bối cảnh bổ sung:

Ví dụ tốt:

Title: {{service}} {{status}} on {{environment}}
Body: {{errorMessage}} at {{timestamp}}
Action required: {{recommendedAction}}

Nên tránh:

Title: Alert
Body: Check logs

Giữ mẫu ngắn gọn

Thông báo hiển thị đẹp nhất khi tiêu đề và nội dung rõ ràng, đi thẳng vào vấn đề:

  • Tiêu đề: 3-8 từ là lý tưởng, tối đa 20 từ
  • Nội dung: 1-3 câu là lý tưởng, tránh những khối chữ dài
  • Ưu tiên: Đặt thông tin quan trọng nhất lên đầu

Giới hạn của thông báo trên iOS:

  • Tiêu đề: khoảng 40 ký tự hiển thị ở dạng thu gọn
  • Nội dung: khoảng 60 ký tự ở dạng thu gọn, nhiều hơn khi mở rộng

Đặt tên nhất quán

Hãy giữ cách đặt tên biến nhất quán trên mọi kênh:

  • Dùng tên rõ ràng, mang tính mô tả: server_name chứ không phải sn
  • Theo một quy ước: snake_case, camelCase hoặc kebab-case
  • Nhất quán giữa các kênh có liên quan
  • Ghi lại những biến cần thiết để các thành viên trong nhóm nắm được

Kiểm thử kỹ lưỡng

Hãy thử mẫu với nhiều tổ hợp biến khác nhau để đảm bảo chúng hiển thị đúng như mong đợi:

  1. Thử khi có đủ mọi biến
  2. Thử khi thiếu các biến tùy chọn
  3. Thử với ký tự đặc biệt và Unicode
  4. Thử với giá trị rất dài
  5. Thử với chuỗi rỗng
  6. Thử với số, boolean, mảng và object

Trình bày dễ đọc

Hãy dùng cách trình bày giúp nội dung thông báo dễ lướt mắt:

🚨 Alert: {{alertName}}
━━━━━━━━━━━━━━━
Server: {{server}}
Metric: {{metric}}  
Value: {{value}}
Time: {{time}}
━━━━━━━━━━━━━━━
Details: {{message}}

Hoặc dùng những nhãn đơn giản:

Server: {{server}}
CPU Usage: {{cpu}}%
Memory: {{memory}}%
Status: {{status}}

Tận dụng biểu thức

Hãy dùng biểu thức để hiển thị các giá trị tính toán và kết quả so sánh:

Title: {{service}} alert — critical: {{severity == "critical"}}
Body: {{metric}} is {{value}} (over threshold: {{value > threshold}})

Biểu thức so sánh và biểu thức logic kết xuất thành true hoặc false; hãy ghép chúng với phần nhãn tĩnh để người đọc hiểu được ý nghĩa.

Lưu ý về múi giờ

Hãy nhớ rằng các biến thời gian hệ thống đều theo UTC. Hãy ghi rõ điều đó hoặc tự quy đổi trong mẫu của bạn:

Alert triggered at {{time}} UTC
Triggered: {{date}} {{time}} (UTC)

Các mẫu hình và ví dụ thường gặp

Giám sát máy chủ

Title: {{hostname}} - {{metric}} Alert
Body: {{metric}} on {{hostname}} is at {{value}}{{unit}}
Threshold: {{threshold}}{{unit}}
Time: {{date}} {{time}}

Pipeline CI/CD

Title: {{repository}} - Build {{status}}
Body: Build #{{buildNumber}} {{status}} in {{duration}}s
Branch: {{branch}}
Commit: {{commit_message}}
Author: {{author}}

Thương mại điện tử

Title: New Order #{{orderNumber}}
Body: Customer: {{customerName}}
Items: {{itemCount}} items
Total: ${{totalAmount}}
Shipping: {{shippingAddress}}

Theo dõi lỗi

Title: {{errorType}} in {{service}}
Body: {{errorMessage}}
File: {{filename}}:{{lineNumber}}
User: {{userId}}
Environment: {{environment}}

Tính năng nâng cao

Mẫu liên kết

Cấu hình một mẫu liên kết tùy chỉnh trong cài đặt nâng cao của kênh để tạo liên kết bấm được trong bản ghi thông báo:

https://dashboard.example.com/orders/{{orderId}}
https://grafana.example.com/d/{{dashboardId}}
https://github.com/{{repo}}/actions/runs/{{runId}}

Nếu không đặt mẫu liên kết, hệ thống sẽ mặc định dùng giá trị của biến externalLink. Cách này rất tiện để truy cập nhanh vào dashboard, log hay tài liệu liên quan ngay từ thông báo.

Hiển thị giá trị tính toán

Mẫu không thể rẽ nhánh bằng logic ba ngôi (? :), và cũng không có toán tử nối chuỗi (+). Thay vào đó, hãy chèn thẳng giá trị và kết quả so sánh, dùng văn bản tĩnh làm nhãn:

Online: {{isOnline}}
High severity: {{severity > 5}}
Errors detected: {{count}}

Biểu thức so sánh kết xuất thành true hoặc false. Để gửi những thông điệp thực sự khác nhau theo từng tình huống, hãy định tuyến các lần kích hoạt bằng Điều kiện của kênh thay vì rẽ nhánh bên trong một mẫu duy nhất.

Điều kiện của kênh

Ngoài việc dùng mẫu trong nội dung thông báo, bạn còn có thể đặt Điều kiện trong cài đặt nâng cao của kênh để quyết định có gửi thông báo hay không. Những điều kiện này dùng cùng cú pháp biểu thức (nhưng không có cặp ngoặc nhọn).

Ví dụ, để chỉ gửi thông báo với những khoản tiền lớn hơn một ngưỡng nhất định:

amount > 100
status == "critical"
temperature > 30 && location == "datacenter"

Cách này giúp tránh mệt mỏi vì cảnh báo bằng cách lọc bỏ những sự kiện không quan trọng trước khi thông báo được gửi đi. Tìm hiểu thêm trong hướng dẫn về Điều kiện của chúng tôi.

Tài liệu liên quan

Xử lý sự cố

Mẫu không hiển thị biến:

  • Kiểm tra tên biến khớp chính xác (phân biệt chữ hoa chữ thường)
  • Xác nhận biến thực sự được truyền vào lúc kích hoạt bằng webhook/email
  • Hãy thử với biến đơn giản trước, rồi mới tăng độ phức tạp

Biến hiện ra rỗng:

  • Xác nhận biến đó có tồn tại trong dữ liệu kích hoạt
  • Kiểm tra lỗi gõ trong tên biến
  • Kiểm tra lại cấu trúc JSON với những thuộc tính lồng nhau

Lỗi biểu thức:

  • Hãy kiểm tra cú pháp với các biểu thức đơn giản trước
  • Đảm bảo các toán tử được cách khoảng đúng
  • Kiểm tra việc truy cập thuộc tính có dùng đúng cú pháp không

Cần trợ giúp? Hãy ghé Trung tâm hỗ trợ hoặc liên hệ echobell@weelone.com.

Mẫu là một cách mạnh mẽ để tạo ra những thông báo linh động, giàu thông tin, mang đến cho người dùng đúng thứ họ cần vào đúng lúc họ cần. Hãy bắt đầu bằng việc thay thế biến đơn giản, rồi dần dần thêm biểu thức và logic điều kiện để xây dựng những hệ thống thông báo tinh vi.