--- title: System szablonów - dynamiczna treść powiadomień sidebarTitle: Szablony description: 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 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**: ```http GET https://hook.echobell.one/t/?amount=100&status=complete ``` 2. **Treść JSON** (przy żądaniach POST): ```http POST https://hook.echobell.one/t/ 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](/docs/conditions) 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](/docs/conditions) 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](/docs/conditions)**, 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](/docs/conditions). ## Powiązana dokumentacja - **[Integracja przez webhooki](/docs/webhook)** — dowiedz się, jak przekazywać zmienne przez webhooki - **[Wyzwalacze e-mail](/docs/email-trigger)** — zmienne dostępne przy wyzwalaczach e-mail - **[Warunki](/docs/conditions)** — filtruj powiadomienia wyrażeniami warunkowymi - **[Pierwsze kroki](/docs)** — skonfiguruj swój pierwszy kanał z szablonami ## 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](/docs/support) 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ń.