Echobell
App Store Google Play

System szablonów - dynamiczna treść powiadomień

Twórz dynamiczne szablony powiadomień ze zmiennymi, wyrażeniami i wartościami systemowymi - plus dobre praktyki dla czytelnych komunikatów alertów.

Szablony w Echobell pozwalają tworzyć dynamiczne, bogate w kontekst powiadomienia dzięki wstawianiu zmiennych do tytułu i treści powiadomienia. Ta funkcja umożliwia budowanie spersonalizowanych i konkretnych alertów, które dopasowują się do danych z wyzwalacza, zamieniając ogólnikowe powiadomienia w informacje gotowe do działania.

Zamiast ogólnego komunikatu „Alert triggered” szablony pozwalają Ci otrzymać konkret w rodzaju „Production server CPU at 95%” albo „Build #142 failed in deploy stage” — od razu z kontekstem, bez konieczności dodatkowego sprawdzania.

Podstawowa składnia szablonów

W szablonach Echobell zmiennych używasz, otaczając je podwójnymi nawiasami klamrowymi:

{{variableName}}

Gdy kanał zostaje wyzwolony, te zmienne są zastępowane rzeczywistymi wartościami przekazanymi w wyzwoleniu. Na przykład jeśli szablon tytułu to You have received ${{amount}}, a kanał zostanie wyzwolony z wartością amount równą 100, powiadomienie wyświetli się jako You have received $100.

Zaawansowane wyrażenia w szablonach

Szablony Echobell obsługują szereg wyrażeń przydatnych w bardziej złożonych scenariuszach:

  • Dostęp do właściwości obiektu
{{user.name}}
{{data["value"]}}
  • Dostęp do elementów tablicy
{{items[0]}}
  • Użycie operatorów porównania
{{status == "active"}}
{{age > 18}}
  • Operatory logiczne
{{isSubscribed && !isPaused}}
{{isUrgent || isHighPriority}}

Obsługiwane są wszystkie standardowe operatory: ==, !=, <, >, <=, >=, &&, || oraz !.

Zmienne szablonu z różnych wyzwalaczy

Wyzwalacze webhook

Wyzwalając kanał webhookiem, możesz przekazać zmienne przez:

  1. Parametry ciągu zapytania:

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

  2. Treść JSON (przy żądaniach POST):

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

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

  3. Zmienne specjalne:

    • externalLink: tworzy klikalny odnośnik w historii powiadomień
    • bodyAsText: treść żądania w postaci zwykłego tekstu, jeśli Content-Type to text/plain
    • header: daje dostęp do nagłówków żądania HTTP (np. {{header["content-type"]}})

Wyzwalacze e-mail

Gdy kanał jest wyzwalany e-mailem, automatycznie dostępne są następujące zmienne:

  • from: adres e-mail nadawcy
  • to: adres e-mail odbiorcy
  • subject: temat wiadomości
  • text: treść wiadomości w postaci zwykłego tekstu
  • html: treść wiadomości w formacie HTML

Zastosowania szablonów

Porównania i wartości logiczne

Wyrażenia z operatorami porównania lub logicznymi renderują swój wynik logiczny jako tekst true albo false:

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

Szablony Echobell nie obsługują wbudowanej logiki if/else (operatora warunkowego). Aby wysyłać różną treść w różnych sytuacjach, użyj warunków kanału do rozdzielenia wyzwoleń albo wstaw surowe wartości bezpośrednio.

Warunki kanału

Poza szablonami treści powiadomienia możesz ustawić w zaawansowanych ustawieniach kanału warunki, które decydują o tym, czy powiadomienie w ogóle ma zostać wysłane. Warunki korzystają z tej samej składni wyrażeń (bez nawiasów klamrowych).

Na przykład, aby wysyłać powiadomienia tylko dla kwot powyżej progu:

amount > 100

Szablony odnośników

Skonfiguruj własny szablon odnośnika w zaawansowanych ustawieniach kanału, aby tworzyć klikalne odnośniki w historii powiadomień:

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

Jeśli szablon odnośnika nie jest ustawiony, domyślnie zostanie użyta wartość zmiennej externalLink.

Systemowe zmienne czasu (UTC)

Te zmienne są zawsze dostępne w szablonach (i warunkach), a ich wartości są wyliczane w strefie UTC.

Poniższe wartości są wstrzykiwane bezpośrednio (płasko) i można ich używać po nazwie:

  • year, month (1–12)
  • dayOfMonth, dayOfWeek (0–6, niedziela = 0)
  • hour (0–23), minute, second
  • date (YYYY-MM-DD), time (HH:mm:ss)
  • iso: znacznik czasu ISO‑8601 (np. 2025-05-06T12:34:56.789Z)

Pozostałe wartości są dostępne wyłącznie w przestrzeni nazw sys. (nie są wstrzykiwane pod płaskimi nazwami):

  • sys.timezone: zawsze "UTC"
  • sys.now: znacznik czasu ISO‑8601 (ta sama wartość co iso)
  • sys.epochMs, sys.epochSeconds: bieżący czas liczony od epoki uniksowej (liczba)
  • sys.monthName: nazwa miesiąca (January–December)
  • sys.dayOfWeekName: nazwa dnia (Sunday–Saturday)

Przestrzeń nazw sys. odzwierciedla też każdą płaską wartość (np. sys.year, sys.hour).

Przykłady:

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

Dobre praktyki

Obsługa brakujących zmiennych

Echobell nie ma operatora wartości domyślnej. Operator || jest czysto logiczny — traktuje obie strony jako wartości logiczne i renderuje true albo false. Zapis {{username || "Anonymous User"}} wyświetli więc dosłowny tekst true lub false, nigdy nazwę użytkownika ani tekst zastępczy.

Gdy zmiennej brakuje, {{variable}} renderuje się po prostu jako pusty ciąg. Zaprojektuj etykiety tak, aby pusta wartość nadal czytała się sensownie:

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

Jeśli potrzebujesz gwarantowanej wartości, wyślij ją jawnie w payloadzie wyzwalacza, zamiast liczyć na wartość zastępczą w szablonie.

Treściwe szablony

Umieszczaj w szablonach kluczowe informacje, aby powiadomienie od razu pozwalało działać, bez szukania dodatkowego kontekstu:

Dobre przykłady:

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

Unikaj:

Title: Alert
Body: Check logs

Pisz zwięźle

Powiadomienia wyglądają najlepiej, gdy tytuł i treść są jasne i konkretne:

  • Tytuły: idealnie 3–8 słów, maksymalnie 20
  • Treści: idealnie 1–3 zdania, bez ścian tekstu
  • Priorytet: najważniejsze informacje na początku

Ograniczenia powiadomień w iOS:

  • Tytuł: około 40 znaków widocznych w widoku zwiniętym
  • Treść: około 60 znaków w widoku zwiniętym, więcej po rozwinięciu

Stosuj spójne nazewnictwo

Utrzymuj spójne nazwy zmiennych we wszystkich kanałach:

  • Używaj jasnych, opisowych nazw: server_name, a nie sn
  • Trzymaj się jednej konwencji: snake_case, camelCase albo kebab-case
  • Zachowuj spójność w powiązanych ze sobą kanałach
  • Udokumentuj oczekiwane zmienne dla członków zespołu

Testuj dokładnie

Sprawdź swoje szablony z różnymi kombinacjami zmiennych, aby mieć pewność, że renderują się zgodnie z oczekiwaniami:

  1. Przetestuj z kompletem zmiennych
  2. Przetestuj z brakiem zmiennych opcjonalnych
  3. Przetestuj ze znakami specjalnymi i Unicode
  4. Przetestuj z bardzo długimi wartościami
  5. Przetestuj z pustymi ciągami
  6. Przetestuj z liczbami, wartościami logicznymi, tablicami i obiektami

Buduj czytelną strukturę

Formatuj treść powiadomienia tak, aby dało się ją szybko przejrzeć wzrokiem:

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

Albo używaj prostych etykiet:

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

Wykorzystuj wyrażenia

Używaj wyrażeń, aby pokazywać wartości wyliczone i wyniki porównań:

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

Wyrażenia porównania i logiczne renderują się jako true lub false; zestawiaj je ze stałym tekstem etykiety, aby nadać im sens.

Pamiętaj o strefach czasowych

Systemowe zmienne czasu podawane są w UTC. Zaznacz to w treści albo przelicz wartości w szablonie:

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

Typowe wzorce i przykłady

Monitoring serwerów

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

Procesy CI/CD

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

E-commerce

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

Śledzenie błędów

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

Funkcje zaawansowane

Szablony odnośników

Skonfiguruj własny szablon odnośnika w zaawansowanych ustawieniach kanału, aby tworzyć klikalne odnośniki w historii powiadomień:

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

Jeśli szablon odnośnika nie jest ustawiony, domyślnie zostanie użyta wartość zmiennej externalLink. To wygodny sposób na szybkie przejście z powiadomienia prosto do właściwego pulpitu, logów czy dokumentacji.

Pokazywanie wartości wyliczonych

Szablony nie potrafią rozgałęziać logiki operatorem warunkowym (? :), nie ma też operatora łączenia napisów (+). Zamiast tego wstawiaj wartości i wyniki porównań bezpośrednio, a jako etykiet używaj stałego tekstu:

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

Wyrażenia porównania renderują się jako true lub false. Aby wysyłać naprawdę różne komunikaty w różnych sytuacjach, rozdzielaj wyzwolenia warunkami kanału, zamiast rozgałęziać logikę w jednym szablonie.

Warunki kanału

Poza szablonami treści powiadomienia możesz ustawić w zaawansowanych ustawieniach kanału warunki, które decydują o tym, czy powiadomienie w ogóle ma zostać wysłane. Warunki korzystają z tej samej składni wyrażeń (bez nawiasów klamrowych).

Na przykład, aby wysyłać powiadomienia tylko dla kwot powyżej progu:

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

Zapobiega to zmęczeniu alertami, odfiltrowując mniej istotne zdarzenia jeszcze przed wysłaniem powiadomienia. Więcej w przewodniku po warunkach.

Powiązana dokumentacja

Rozwiązywanie problemów

Szablon nie podstawia zmiennych:

  • Sprawdź, czy nazwy zmiennych zgadzają się dokładnie (wielkość liter ma znaczenie)
  • Upewnij się, że zmienne są przekazywane w wyzwalaczu webhook lub e-mail
  • Zacznij od prostych zmiennych, a złożoność dokładaj później

Zmienne wyświetlają się jako puste:

  • Potwierdź, że zmienna faktycznie występuje w danych wyzwalacza
  • Poszukaj literówek w nazwach zmiennych
  • Sprawdź strukturę JSON przy właściwościach zagnieżdżonych

Błędy w wyrażeniach:

  • Zweryfikuj składnię, zaczynając od prostych wyrażeń
  • Zadbaj o poprawne odstępy wokół operatorów
  • Sprawdź, czy dostęp do właściwości używa poprawnej składni

Potrzebujesz pomocy? Zajrzyj do centrum wsparcia lub napisz na echobell@weelone.com.

Szablony to skuteczny sposób na tworzenie dynamicznych, treściwych powiadomień, które dają odbiorcom dokładnie te informacje, których potrzebują, i to wtedy, gdy są potrzebne. Zacznij od zwykłego podstawiania zmiennych, a potem stopniowo dodawaj wyrażenia i logikę warunkową, budując coraz bardziej dopracowany system powiadomień.