--- title: Система шаблонов — динамическое содержимое уведомлений sidebarTitle: Шаблоны description: Создавайте динамические шаблоны уведомлений с переменными, выражениями и системными значениями, а также изучите практики написания понятных оповещений. --- # Шаблоны в Echobell Шаблоны в 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. **Параметры строки запроса**: ```http GET https://hook.echobell.one/t/?amount=100&status=complete ``` 2. **Тело JSON** (для POST-запросов): ```http POST https://hook.echobell.one/t/ 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 (тернарный оператор). Чтобы отправлять разное содержимое в разных ситуациях, используйте [Условия](/docs/conditions) канала для маршрутизации триггеров или подставляйте исходные значения напрямую. ### Условия канала Помимо шаблонов в содержимом уведомления, в расширенных настройках канала можно задать **Условия**, которые определяют, нужно ли вообще отправлять уведомление. Условия используют тот же синтаксис выражений (без фигурных скобок). Например, чтобы отправлять уведомления только для сумм выше порога: ``` 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`. Чтобы отправлять действительно разные сообщения для разных ситуаций, маршрутизируйте триггеры через [Условия](/docs/conditions) канала, а не ветвите логику внутри одного шаблона. ### Условия канала Помимо шаблонов в содержимом уведомления, в расширенных настройках канала можно задать **[Условия](/docs/conditions)**, которые определяют, нужно ли вообще отправлять уведомление. Условия используют тот же синтаксис выражений (без фигурных скобок). Например, чтобы отправлять уведомления только для сумм выше порога: ``` amount > 100 status == "critical" temperature > 30 && location == "datacenter" ``` Так некритичные события отсеиваются до отправки уведомлений, и усталость от оповещений не накапливается. Подробнее — в [руководстве по условиям](/docs/conditions). ## Смежная документация - **[Интеграция по вебхуку](/docs/webhook)** — как передавать переменные через вебхуки - **[Триггеры по email](/docs/email-trigger)** — переменные, доступные в триггерах по email - **[Условия](/docs/conditions)** — фильтрация уведомлений условными выражениями - **[Начало работы](/docs)** — настройте первый канал с шаблонами ## Устранение неполадок **Шаблон не подставляет переменные:** - Проверьте, что имена переменных совпадают точно (регистр учитывается) - Убедитесь, что переменные действительно передаются в вебхуке или триггере по email - Начните с простых переменных, затем усложняйте **Переменные выводятся пустыми:** - Убедитесь, что переменная есть в данных триггера - Проверьте опечатки в именах переменных - Проверьте структуру JSON для вложенных свойств **Ошибки в выражениях:** - Сначала проверьте синтаксис на простых выражениях - Убедитесь, что вокруг операторов расставлены пробелы - Проверьте, что доступ к свойствам записан по правилам синтаксиса Нужна помощь? Загляните в [Центр поддержки](/docs/support) или напишите на echobell@weelone.com. --- Шаблоны — мощный способ собирать динамические, информативные уведомления, которые дают пользователям ровно ту информацию, которая им нужна, и ровно тогда, когда она нужна. Начните с простой подстановки переменных, а затем постепенно добавляйте выражения и условную логику, чтобы выстроить продуманную систему уведомлений.