Sistema di modelli - Contenuto dinamico delle notifiche

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:

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

2. Corpo JSON (per le richieste POST):

   POST https://hook.echobell.one/t/<channel-token>
   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 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 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 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.

Documentazione correlata

• Integrazione webhook - Come passare le variabili tramite webhook
• Trigger email - Le variabili disponibili con i trigger via email
• Condizioni - Filtra le notifiche con espressioni condizionali
• Guida introduttiva - 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 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.