--- title: Sistema di modelli - Contenuto dinamico delle notifiche sidebarTitle: Modelli description: Crea modelli di notifica dinamici con variabili, espressioni e valori di sistema, oltre alle best practice per scrivere avvisi chiari. --- # I modelli in Echobell Con i modelli di Echobell puoi creare notifiche dinamiche e ricche di contesto, inserendo variabili nel titolo e nel corpo delle tue notifiche. È una funzione potente che ti permette di generare avvisi personalizzati e informativi, capaci di adattarsi ai dati del trigger e di trasformare notifiche generiche in informazioni su cui puoi agire subito. Invece di ricevere un generico "Avviso attivato", con i modelli puoi creare notifiche precise come "CPU del server di produzione al 95%" oppure "Build #142 fallita nella fase di deploy": il contesto arriva subito, senza che tu debba andare a cercare altro. ## Sintassi di base dei modelli Nei modelli di Echobell puoi usare le variabili racchiudendole tra doppie parentesi graffe: ``` {{variableName}} ``` Quando un canale viene attivato, queste variabili vengono sostituite con i valori effettivi trasmessi dal trigger. Ad esempio, se il modello del titolo è `You have received ${{amount}}` e attivi il canale con un valore di `amount` pari a 100, la notifica risultante mostrerà `You have received $100`. ## Espressioni avanzate nei modelli I modelli di Echobell supportano diverse espressioni per gli scenari più complessi: - Accesso alle proprietà degli oggetti ``` {{user.name}} {{data["value"]}} ``` - Accesso agli elementi di un array ``` {{items[0]}} ``` - Uso degli operatori di confronto ``` {{status == "active"}} {{age > 18}} ``` - Operatori logici ``` {{isSubscribed && !isPaused}} {{isUrgent || isHighPriority}} ``` Sono supportati tutti gli operatori standard: `==`, `!=`, `<`, `>`, `<=`, `>=`, `&&`, `||` e `!`. ## Variabili dei modelli dai diversi trigger ### Trigger webhook Quando attivi un canale tramite webhook, puoi passare le variabili in questi modi: 1. **Parametri della query string**: ```http GET https://hook.echobell.one/t/?amount=100&status=complete ``` 2. **Corpo JSON** (per le richieste POST): ```http POST https://hook.echobell.one/t/ Content-Type: application/json { "amount": 100, "status": "complete", "user": { "name": "John", "id": 12345 } } ``` 3. **Variabili speciali**: - `externalLink`: fornisce un link cliccabile nei record delle notifiche - `bodyAsText`: il contenuto in testo semplice del corpo della richiesta, se il `Content-Type` è `text/plain` - `header`: dà accesso agli header della richiesta HTTP (ad esempio `{{header["content-type"]}}`) ### Trigger email Quando un canale viene attivato via email, queste variabili sono disponibili in automatico: - `from`: l'indirizzo email del mittente - `to`: l'indirizzo email del destinatario - `subject`: l'oggetto dell'email - `text`: il contenuto in testo semplice dell'email - `html`: il contenuto HTML dell'email ## Casi d'uso dei modelli ### Confronti e valori booleani Le espressioni che usano operatori di confronto o logici restituiscono il risultato booleano come testo `true` o `false`: ``` Payment over $1000: {{amount > 1000}} High priority: {{isUrgent || isImportant}} ``` I modelli di Echobell **non** supportano la logica if/else inline (l'operatore ternario). Per inviare contenuti diversi in situazioni diverse, usa le [Condizioni](/docs/conditions) del canale per instradare i trigger, oppure interpola direttamente i valori grezzi. ### Condizioni del canale Oltre a usare i modelli nel contenuto delle notifiche, nelle impostazioni avanzate del canale puoi definire delle **Condizioni** che stabiliscono se la notifica vada inviata o meno. Queste condizioni usano la stessa sintassi delle espressioni, ma senza le parentesi graffe. Ad esempio, per inviare notifiche solo quando l'importo supera una certa soglia: ``` amount > 100 ``` ## Modelli di link Configura un modello di link personalizzato nelle impostazioni avanzate del canale per avere link cliccabili nei record delle notifiche: ``` https://dashboard.example.com/orders/{{orderId}} ``` Se non imposti nessun modello di link, per impostazione predefinita viene usato il valore della variabile `externalLink`. ## Variabili di sistema per data e ora (UTC) Queste variabili sono sempre disponibili nei modelli (e nelle condizioni) e vengono calcolate in UTC. I valori seguenti vengono iniettati direttamente (in forma piatta) e puoi richiamarli per nome: - `year`, `month` (1–12) - `dayOfMonth`, `dayOfWeek` (0–6, domenica = 0) - `hour` (0–23), `minute`, `second` - `date` (`YYYY-MM-DD`), `time` (`HH:mm:ss`) - `iso`: timestamp ISO‑8601 (ad esempio `2025-05-06T12:34:56.789Z`) Altri valori sono disponibili **solo** nel namespace `sys.` (non vengono iniettati come nomi piatti): - `sys.timezone`: sempre `"UTC"` - `sys.now`: timestamp ISO‑8601 (stesso valore di `iso`) - `sys.epochMs`, `sys.epochSeconds`: tempo trascorso dall'epoch Unix (numero) - `sys.monthName`: nome del mese (`January`–`December`) - `sys.dayOfWeekName`: nome del giorno (`Sunday`–`Saturday`) Il namespace `sys.` rispecchia anche tutti i valori piatti (ad esempio `sys.year`, `sys.hour`). Esempi: ``` Sent at {{date}} {{time}} {{sys.timezone}} Today is {{sys.dayOfWeekName}}, {{sys.monthName}} {{dayOfMonth}}, {{year}} Epoch: {{sys.epochSeconds}} ``` ## Best practice ### Gestisci le variabili mancanti Echobell non ha **nessun operatore per i valori predefiniti**. L'operatore `||` è puramente logico: valuta entrambi i lati come booleani e restituisce `true` o `false`. Quindi `{{username || "Anonymous User"}}` produce letteralmente il testo `true` o `false`, mai il nome utente né la stringa di ripiego. Quando una variabile manca, `{{variable}}` viene semplicemente reso come stringa vuota. Progetta le etichette in modo che il testo resti chiaro anche con un valore vuoto: ``` User: {{username}} Server: {{serverName}} Errors detected: {{errorCount}} ``` Se ti serve un valore garantito, invialo esplicitamente nel payload del trigger invece di affidarti a un ripiego del modello. ### Modelli informativi Inserisci nei modelli le informazioni chiave, così le notifiche diventano subito utilizzabili senza bisogno di altro contesto: **Esempi validi:** ``` Title: {{service}} {{status}} on {{environment}} Body: {{errorMessage}} at {{timestamp}} Action required: {{recommendedAction}} ``` **Da evitare:** ``` Title: Alert Body: Check logs ``` ### Mantieni i modelli concisi Le notifiche rendono al meglio quando titolo e corpo sono chiari e diretti: - **Titoli**: da 3 a 8 parole è l'ideale, massimo 20 - **Corpo**: da 1 a 3 frasi è l'ideale, evita i muri di testo - **Priorità**: metti per prime le informazioni più importanti Limiti delle notifiche su iOS: - Titolo: circa 40 caratteri visibili nella vista compressa - Corpo: circa 60 caratteri nella vista compressa, di più quando la espandi ### Usa nomi coerenti Mantieni una nomenclatura uniforme per le variabili in tutti i tuoi canali: - Usa nomi chiari e descrittivi: `server_name`, non `sn` - Segui una convenzione: snake_case, camelCase o kebab-case - Resta coerente tra canali collegati tra loro - Documenta le variabili attese per il resto del team ### Fai test approfonditi Prova i tuoi modelli con combinazioni diverse di variabili, per verificare che vengano resi come ti aspetti: 1. Prova con tutte le variabili presenti 2. Prova con le variabili facoltative mancanti 3. Prova con caratteri speciali e Unicode 4. Prova con valori molto lunghi 5. Prova con stringhe vuote 6. Prova con numeri, booleani, array e oggetti ### Struttura il contenuto per la leggibilità Usa la formattazione per rendere il contenuto della notifica facile da scorrere: ``` 🚨 Alert: {{alertName}} ━━━━━━━━━━━━━━━ Server: {{server}} Metric: {{metric}} Value: {{value}} Time: {{time}} ━━━━━━━━━━━━━━━ Details: {{message}} ``` Oppure usa etichette semplici: ``` Server: {{server}} CPU Usage: {{cpu}}% Memory: {{memory}}% Status: {{status}} ``` ### Sfrutta le espressioni Usa le espressioni per far emergere valori calcolati e risultati dei confronti: ``` Title: {{service}} alert — critical: {{severity == "critical"}} Body: {{metric}} is {{value}} (over threshold: {{value > threshold}}) ``` Le espressioni di confronto e quelle logiche vengono rese come `true` o `false`: abbinale a un'etichetta di testo fisso per dare loro un significato. ### Tieni conto dei fusi orari Ricorda che le variabili di sistema per data e ora sono in UTC. Indicalo nel testo oppure converti il valore nei tuoi modelli: ``` Alert triggered at {{time}} UTC Triggered: {{date}} {{time}} (UTC) ``` ## Schemi ricorrenti ed esempi ### Monitoraggio dei server ``` 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}} ``` ### E-commerce ``` Title: New Order #{{orderNumber}} Body: Customer: {{customerName}} Items: {{itemCount}} items Total: ${{totalAmount}} Shipping: {{shippingAddress}} ``` ### Tracciamento degli errori ``` Title: {{errorType}} in {{service}} Body: {{errorMessage}} File: {{filename}}:{{lineNumber}} User: {{userId}} Environment: {{environment}} ``` ## Funzionalità avanzate ### Modelli di link Configura un **modello di link** personalizzato nelle impostazioni avanzate del canale per creare link cliccabili nei record delle notifiche: ``` https://dashboard.example.com/orders/{{orderId}} https://grafana.example.com/d/{{dashboardId}} https://github.com/{{repo}}/actions/runs/{{runId}} ``` Se non imposti nessun modello di link, per impostazione predefinita viene usato il valore della variabile `externalLink`. È comodo per raggiungere al volo dashboard, log o documentazione pertinenti direttamente dalla notifica. ### Mostrare i valori calcolati I modelli non possono ramificarsi con la logica ternaria (`? :`) e non esiste un operatore di concatenazione di stringhe (`+`). Interpola invece direttamente i valori e i risultati dei confronti, usando testo fisso per le etichette: ``` Online: {{isOnline}} High severity: {{severity > 5}} Errors detected: {{count}} ``` Le espressioni di confronto vengono rese come `true` o `false`. Per inviare messaggi davvero diversi a seconda della situazione, instrada i trigger con le [Condizioni](/docs/conditions) del canale, invece di ramificare all'interno di un unico modello. ### Condizioni del canale Oltre a usare i modelli nel contenuto delle notifiche, nelle impostazioni avanzate del canale puoi definire delle **[Condizioni](/docs/conditions)** che stabiliscono se la notifica vada inviata o meno. Queste condizioni usano la stessa sintassi delle espressioni, ma senza le parentesi graffe. Ad esempio, per inviare notifiche solo quando l'importo supera una certa soglia: ``` amount > 100 status == "critical" temperature > 30 && location == "datacenter" ``` Così eviti l'alert fatigue, perché gli eventi non critici vengono filtrati prima che parta qualsiasi notifica. Scopri di più nella nostra [guida alle condizioni](/docs/conditions). ## Documentazione correlata - **[Integrazione webhook](/docs/webhook)** - Come passare le variabili tramite webhook - **[Trigger email](/docs/email-trigger)** - Le variabili disponibili con i trigger via email - **[Condizioni](/docs/conditions)** - Filtra le notifiche con espressioni condizionali - **[Guida introduttiva](/docs)** - Configura il tuo primo canale con i modelli ## Risoluzione dei problemi **Il modello non sostituisce le variabili:** - Controlla che i nomi delle variabili corrispondano esattamente (maiuscole e minuscole fanno differenza) - Verifica che le variabili vengano davvero passate dal trigger webhook o email - Prova prima con variabili semplici, poi aggiungi complessità **Le variabili risultano vuote:** - Conferma che la variabile esista nei dati del trigger - Controlla che non ci siano errori di battitura nei nomi delle variabili - Verifica la struttura del JSON per le proprietà annidate **Errori nelle espressioni:** - Convalida la sintassi partendo da espressioni semplici - Assicurati che gli operatori siano separati correttamente da spazi - Controlla che l'accesso alle proprietà usi la sintassi corretta Ti serve aiuto? Vai al nostro [centro assistenza](/docs/support) oppure scrivi a echobell@weelone.com. --- I modelli sono uno strumento potente per creare notifiche dinamiche e informative, che danno a chi le riceve esattamente le informazioni di cui ha bisogno, nel momento in cui servono. Parti dalla semplice sostituzione delle variabili, poi aggiungi via via espressioni e logica condizionale per costruire sistemi di notifica più sofisticati.