Система шаблонов — динамическое содержимое уведомлений

Шаблоны в Echobell позволяют создавать динамические уведомления с богатым контекстом: вы подставляете переменные в заголовок и текст уведомления. Эта возможность даёт персонализированные и информативные оповещения, которые подстраиваются под данные триггера и превращают общие уведомления в информацию, по которой можно действовать.

Вместо общего сообщения «Сработало оповещение» шаблоны позволяют собирать конкретные уведомления вроде «CPU на production-сервере — 95%» или «Сборка #142 упала на этапе deploy» — контекст виден сразу, без дополнительных разбирательств.

Базовый синтаксис шаблонов

В шаблонах Echobell переменные заключаются в двойные фигурные скобки:

{{variableName}}

Когда канал срабатывает, эти переменные заменяются фактическими значениями, переданными через триггер. Например, если шаблон заголовка — You have received ${{amount}}, а канал вызывается со значением amount, равным 100, уведомление отобразится как You have received $100.

Расширенные выражения в шаблонах

Шаблоны Echobell поддерживают разные выражения для более сложных сценариев:

• Доступ к свойствам объекта

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

• Доступ к элементам массива

{{items[0]}}

• Использование операторов сравнения

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

• Логические операторы

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

Поддерживаются все стандартные операторы: ==, !=, <, >, <=, >=, &&, || и !.

Переменные шаблонов из разных триггеров

Триггеры по вебхуку

При запуске через вебхук переменные можно передать так:

1. Параметры строки запроса:

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

2. Тело JSON (для POST-запросов):

   POST https://hook.echobell.one/t/<channel-token>
   Content-Type: application/json
   
   {
     "amount": 100,
     "status": "complete",
     "user": {
       "name": "John",
       "id": 12345
     }
   }

3. Специальные переменные:

   • externalLink: добавляет кликабельную ссылку в записи уведомлений
   • bodyAsText: текстовое содержимое тела запроса, если Content-Type — text/plain
   • header: доступ к заголовкам HTTP-запроса (например, {{header["content-type"]}})

Триггеры по email

Когда канал запускается по email, автоматически доступны следующие переменные:

• from: адрес отправителя
• to: адрес получателя
• subject: тема письма
• text: текстовое содержимое письма
• html: HTML-содержимое письма

Сценарии использования шаблонов

Сравнения и логические значения

Выражения с операторами сравнения или логическими операторами выводят булев результат как текст true или false:

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

Шаблоны Echobell не поддерживают встроенную логику if/else (тернарный оператор). Чтобы отправлять разное содержимое в разных ситуациях, используйте Условия канала для маршрутизации триггеров или подставляйте исходные значения напрямую.

Условия канала

Помимо шаблонов в содержимом уведомления, в расширенных настройках канала можно задать Условия, которые определяют, нужно ли вообще отправлять уведомление. Условия используют тот же синтаксис выражений (без фигурных скобок).

Например, чтобы отправлять уведомления только для сумм выше порога:

amount > 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).

Примеры:

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

Рекомендации

Обработка отсутствующих переменных

В Echobell нет оператора значения по умолчанию. Оператор || чисто логический: он приводит обе стороны к булеву типу и выводит true или false. Поэтому {{username || "Anonymous User"}} выводит буквальный текст true или false, а не имя пользователя и не запасную строку.

Если переменной нет, {{variable}} выводится как пустая строка. Составляйте подписи так, чтобы текст оставался понятным и с пустым значением:

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

Если значение нужно гарантированно, передавайте его явно в полезной нагрузке триггера, а не полагайтесь на запасной вариант в шаблоне.

Информативные шаблоны

Включайте в шаблоны ключевую информацию, чтобы по уведомлению можно было действовать без дополнительного контекста:

Удачные примеры:

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

Избегайте:

Title: Alert
Body: Check logs

Пишите шаблоны кратко

Уведомления читаются лучше всего, когда заголовок и текст ясны и по делу:

• Заголовки: оптимально 3–8 слов, максимум 20 слов
• Текст: оптимально 1–3 предложения, без простыней текста
• Приоритет: самое важное — в начале

Ограничения уведомлений в iOS:

• Заголовок: около 40 символов видно в свёрнутом виде
• Текст: около 60 символов в свёрнутом виде, больше — в развёрнутом

Единообразные имена

Придерживайтесь единой схемы именования переменных во всех каналах:

• Используйте понятные описательные имена: server_name, а не sn
• Следуйте одному соглашению: snake_case, camelCase или kebab-case
• Сохраняйте единообразие в связанных каналах
• Документируйте ожидаемые переменные для коллег

Тщательно тестируйте

Проверяйте шаблоны на разных комбинациях переменных, чтобы убедиться, что они выводятся как задумано:

1. Проверьте со всеми переменными
2. Проверьте, когда необязательные переменные отсутствуют
3. Проверьте на спецсимволах и Unicode
4. Проверьте на очень длинных значениях
5. Проверьте на пустых строках
6. Проверьте на числах, булевых значениях, массивах и объектах

Структура для читаемости

Форматируйте содержимое уведомления так, чтобы его было легко просматривать:

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

Или используйте простые подписи:

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

Используйте выражения

С помощью выражений выводите вычисленные значения и результаты сравнений:

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

Выражения сравнения и логические выражения выводятся как true или false; сопровождайте их статичной подписью, чтобы смысл был понятен.

Учитывайте часовые пояса

Помните, что системные переменные времени указаны в UTC. Отразите это в документации или преобразуйте время в шаблонах:

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

Типовые схемы и примеры

Мониторинг серверов

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

CI/CD-пайплайны

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

Электронная коммерция

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

Отслеживание ошибок

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

Дополнительные возможности

Шаблоны ссылок

Настройте собственный шаблон ссылки в расширенных настройках канала, чтобы в записях уведомлений появлялись кликабельные ссылки:

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

Если шаблон ссылки не задан, по умолчанию используется значение переменной externalLink. Это удобно для быстрого перехода к нужным дашбордам, логам или документации прямо из уведомления.

Вывод вычисленных значений

В шаблонах нет ветвления через тернарный оператор (? :) и нет оператора конкатенации строк (+). Вместо этого подставляйте значения и результаты сравнений напрямую, а подписи задавайте статичным текстом:

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

Выражения сравнения выводятся как true или false. Чтобы отправлять действительно разные сообщения для разных ситуаций, маршрутизируйте триггеры через Условия канала, а не ветвите логику внутри одного шаблона.

Условия канала

Помимо шаблонов в содержимом уведомления, в расширенных настройках канала можно задать Условия, которые определяют, нужно ли вообще отправлять уведомление. Условия используют тот же синтаксис выражений (без фигурных скобок).

Например, чтобы отправлять уведомления только для сумм выше порога:

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

Так некритичные события отсеиваются до отправки уведомлений, и усталость от оповещений не накапливается. Подробнее — в руководстве по условиям.

Смежная документация

• Интеграция по вебхуку — как передавать переменные через вебхуки
• Триггеры по email — переменные, доступные в триггерах по email
• Условия — фильтрация уведомлений условными выражениями
• Начало работы — настройте первый канал с шаблонами

Устранение неполадок

Шаблон не подставляет переменные:

• Проверьте, что имена переменных совпадают точно (регистр учитывается)
• Убедитесь, что переменные действительно передаются в вебхуке или триггере по email
• Начните с простых переменных, затем усложняйте

Переменные выводятся пустыми:

• Убедитесь, что переменная есть в данных триггера
• Проверьте опечатки в именах переменных
• Проверьте структуру JSON для вложенных свойств

Ошибки в выражениях:

• Сначала проверьте синтаксис на простых выражениях
• Убедитесь, что вокруг операторов расставлены пробелы
• Проверьте, что доступ к свойствам записан по правилам синтаксиса

Нужна помощь? Загляните в Центр поддержки или напишите на echobell@weelone.com.

---

Шаблоны — мощный способ собирать динамические, информативные уведомления, которые дают пользователям ровно ту информацию, которая им нужна, и ровно тогда, когда она нужна. Начните с простой подстановки переменных, а затем постепенно добавляйте выражения и условную логику, чтобы выстроить продуманную систему уведомлений.