> ## Documentation Index > Fetch the complete documentation index at: https://docs.switchbord.ai/llms.txt > Use this file to discover all available pages before exploring further. # Guida di riferimento alle regole dei modelli > Ogni regola del validatore dei modelli WhatsApp collegata ai motivi di rifiuto di Meta — con esempi DA FARE e DA NON FARE per ciascuna. Questa pagina è il riferimento autorevole per ogni regola strutturale che Switchbord verifica prima di inviare un modello a Meta. Ogni sezione è collegata al codice di errore emesso dal validatore lato client (vedi BORD-335), così puoi passare direttamente da un banner rosso nell'editor alla soluzione. Tutte le regole sono applicate sia dal linter lato client di Switchbord sia dal validatore di Meta al momento dell'invio. Il revisore umano di Meta aggiunge un secondo livello di controlli sul contenuto (vedi [Modelli di marketing](/it/whatsapp/marketing-templates)). ## name-regex I nomi dei modelli vengono usati come identificatori stabili su Meta, nei webhook e nel nostro database. Meta impone caratteri solo minuscoli affinché i nomi siano compatibili con gli URL e facilmente confrontabili tra i diversi BSP. **Regola:** `^[a-z][a-z0-9_]{0,511}$` — solo lettere minuscole, cifre e underscore. Nessuno spazio, trattino, maiuscola, punto o carattere accentato. Deve essere univoco per WABA e per lingua. **DA FARE** ```text theme={null} booking_confirmed invoice_ready winback_30d ``` **DA NON FARE** ```text theme={null} Booking Confirmed // spazi e maiuscole invoice-ready // trattino booking.v2 // punto prenotazioneConfermata // camelCase ``` Documentazione Meta: [Linee guida sui modelli — denominazione](https://developers.facebook.com/docs/whatsapp/message-templates/guidelines). ## leading-variable Meta rifiuta un testo del corpo che inizia con un segnaposto, perché appare goffo su mobile e non fornisce al modello alcun punto di riferimento per la classificazione della categoria. Un corpo che inizia con un nome o un saluto si legge come un messaggio; uno che inizia con `{{1}}` si legge come una fuga di dati del modello. **DA FARE** ```text theme={null} Ciao {{1}}, la tua prenotazione è confermata. ``` **DA NON FARE** ```text theme={null} {{1}} è confermata. ``` Documentazione Meta: [Linee guida sui modelli di messaggio](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## trailing-variable Lo speculare della regola leading-variable. Un corpo che termina con `{{N}}` — anche con un punto finale — viene rifiutato. Aggiungi almeno una parola fissa dopo l'ultimo segnaposto, idealmente una frase completa di contesto. **DA FARE** ```text theme={null} Rimborso di {{1}} EUR accreditato entro 7 giorni. ``` **DA NON FARE** ```text theme={null} Rimborso di {{1}} ``` Documentazione Meta: [Linee guida sui modelli di messaggio](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## adjacent-variables Due segnaposto con solo spazi o punteggiatura tra loro vengono rifiutati. Meta non riesce a rendere il confine in modo pulito e non può classificare l'intento quando il corpo è di fatto un elenco di parametri. Metti almeno una parola vera tra ogni coppia. **DA FARE** ```text theme={null} Ciao {{1}}, il tuo codice ordine è {{2}}. ``` **DA NON FARE** ```text theme={null} {{1}}, {{2}} {{1}} {{2}} {{1}}-{{2}} ``` Documentazione Meta: [Linee guida sui modelli di messaggio](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates). ## missing-example Ogni `{{n}}` in un `HEADER`, `BODY`, o in un bottone URL dinamico deve avere un esempio realistico corrispondente. Meta usa gli esempi per generare l'anteprima mostrata ai revisori e per classificare la categoria del modello. Un modello con segnaposto ma senza esempi viene rifiutato al momento dell'invio. **DA FARE** ```json theme={null} { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ships today.", "example": { "body_text": [["Marco Rossi", "GBV-2025-0042"]] } } ``` **DA NON FARE** ```json theme={null} { "type": "BODY", "text": "Hi {{1}}, your order {{2}} ships today." } ``` Documentazione Meta: [Creare e inviare un modello](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates). ## example-count-mismatch La lunghezza dell'array di esempi deve essere uguale al numero di segnaposto distinti. Tre token `{{n}}` richiedono esattamente tre stringhe di esempio — non due, non quattro. Questo controllo viene eseguito per ogni componente (corpo, testo dell'intestazione, bottone URL). **DA FARE** ```json theme={null} "text": "Hi {{1}}, order {{2}} — total {{3}} EUR.", "example": { "body_text": [["Marco", "GBV-0042", "450,00"]] } ``` **DA NON FARE** ```json theme={null} "text": "Hi {{1}}, order {{2}} — total {{3}} EUR.", "example": { "body_text": [["Marco", "GBV-0042"]] } // solo 2 esempi per 3 variabili ``` Documentazione Meta: [Parametri dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#examples). ## numeric-only-example I valori di esempio devono essere realistici — cioè devono contenere caratteri alfabetici o un token alfanumerico chiaramente significativo (un importo con simbolo di valuta, una data, un codice ordine). Un numero nudo, un singolo simbolo o una stringa simile a un codice senza contesto viene rifiutato perché non rappresenta come un destinatario reale vedrà effettivamente il messaggio. **DA FARE** ```json theme={null} "example": { "body_text": [["20%", "Parigi", "15 maggio 2025", "FLASH20"]] } ``` **DA NON FARE** ```json theme={null} "example": { "body_text": [["20", "5", "2025", "20"]] } // numeri nudi "example": { "body_text": [["%", "€", "—", "."]] } // solo simboli ``` Incorpora l'unità di misura direttamente nell'esempio — scrivi `"20%"`, non `"20"` con il `%` adiacente nel corpo. Questo elimina l'euristica del "numero nudo" e produce lo stesso risultato visivo. Documentazione Meta: [Valori di esempio](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#examples). ## sequential-numbering I segnaposto devono iniziare da `{{1}}` e procedere in sequenza senza salti né duplicati. `{{1}}, {{2}}, {{3}}` è valido; `{{1}}, {{3}}` non lo è; `{{2}}, {{3}}` non lo è (deve iniziare da 1). Il validatore estrae gli indici univoci, li ordina e verifica che l'elenco risultante sia uguale a `[1..N]`. **DA FARE** ```text theme={null} Hi {{1}}, order {{2}} ships {{3}}. ``` **DA NON FARE** ```text theme={null} Hi {{1}}, order {{3}}. // manca {{2}} Hi {{2}}, welcome. // non inizia da 1 Hi {{1}}, {{1}} again. // indice duplicato ``` Documentazione Meta: [Parametri dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates). ## params-words-ratio Un modello in cui i segnaposto dominano rispetto al testo fisso si legge come un dump di dati grezzi e viene segnalato durante la revisione del contenuto. Il linter di Switchbord avvisa quando il rapporto tra variabili e parole totali supera circa **1 su 4** — un modello con tre token `{{n}}` dovrebbe avere almeno dodici parole di testo fisso attorno a esse. **DA FARE** ```text theme={null} Ciao {{1}}, la tua prenotazione per {{2}} è confermata. Il codice viaggio è {{3}}, conservalo per il check-in. ``` (12 parole fisse attorno a 3 segnaposto) **DA NON FARE** ```text theme={null} {{1}}: {{2}} — {{3}} ``` (3 segnaposto, 2 token fissi) Documentazione Meta: [Qualità dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/guidelines). ## length-caps Ogni componente ha un limite massimo di caratteri rigido. Conta la stringa grezza del modello, inclusi i segnaposto — l'espansione in fase di esecuzione non conta rispetto al limite. | Componente | Limite | | ----------------- | ------------------ | | Testo HEADER | **60** caratteri | | Testo BODY | **1024** caratteri | | Testo FOOTER | **60** caratteri | | Etichetta bottone | **25** caratteri | **DA FARE** ```text theme={null} HEADER: "Estate 2025 — offerte" (22 caratteri) FOOTER: "Rispondi STOP per non ricevere più." (35 caratteri) Button: "Scarica PDF" (11 caratteri) ``` **DA NON FARE** ```text theme={null} HEADER: "Offerta esclusiva di fine stagione ..." (> 60 caratteri) Button: "Scopri tutte le offerte di questo mese" (> 25 caratteri) ``` Documentazione Meta: [Componenti dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). ## button-limits I bottoni hanno limiti massimi rigidi per tipo. Superare uno qualsiasi di questi limiti fa rifiutare l'intero modello al momento dell'invio. | Tipo di bottone | Massimo | | --------------- | ----------------------------------- | | `QUICK_REPLY` | **3** per modello | | `URL` | **2** (max 1 con suffisso dinamico) | | `PHONE_NUMBER` | **1** | | `COPY_CODE` | **1** | | `FLOW` | **1** | | **Totale** | **10** su tutti i tipi | I bottoni URL dinamici devono avere `{{1}}` come unica variabile, presente **alla fine** del percorso URL o del valore di query — mai nel nome host. **DA FARE** ```json theme={null} "buttons": [ { "type": "QUICK_REPLY", "text": "Mare" }, { "type": "QUICK_REPLY", "text": "Montagna" }, { "type": "QUICK_REPLY", "text": "Città d'arte" }, { "type": "URL", "text": "Scarica PDF", "url": "https://gbviaggi.it/fattura/{{1}}", "example": ["https://gbviaggi.it/fattura/2025-0142"] } ] ``` **DA NON FARE** ```json theme={null} "buttons": [ { "type": "QUICK_REPLY", "text": "A" }, { "type": "QUICK_REPLY", "text": "B" }, { "type": "QUICK_REPLY", "text": "C" }, { "type": "QUICK_REPLY", "text": "D" } // 4 > massimo 3 ] "url": "https://{{1}}.example.com" // variabile nel nome host "url": "https://example.com/{{1}}/{{2}}" // più di una variabile ``` Documentazione Meta: [Bottoni dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#buttons). ## component-ordering I componenti di un modello devono apparire nell'ordine `HEADER → BODY → FOOTER → BUTTONS`. Ogni componente può apparire al massimo una volta, eccetto `BODY` che è richiesto esattamente una volta. Meta normalizza l'ordine in alcuni casi ma rifiuta i duplicati e i tipi sconosciuti con il codice 100. **DA FARE** ```json theme={null} "components": [ { "type": "HEADER", "format": "TEXT", "text": "Estate 2025" }, { "type": "BODY", "text": "Ciao {{1}}, ..." }, { "type": "FOOTER", "text": "Rispondi STOP." }, { "type": "BUTTONS", "buttons": [ ... ] } ] ``` **DA NON FARE** ```json theme={null} "components": [ { "type": "BODY", "text": "..." }, { "type": "HEADER", "format": "TEXT", "text": "..." }, // posizione errata { "type": "BODY", "text": "..." } // duplicato ] ``` Documentazione Meta: [Componenti dei modelli](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). ## footer-has-variables I footer servono per testo statico e legalmente rilevante — l'identità del mittente, l'istruzione di opt-out, un'informativa. Non possono contenere segnaposto `{{n}}`. Metti i dati generati in fase di esecuzione nel corpo. **DA FARE** ```json theme={null} { "type": "FOOTER", "text": "GB Viaggi — Rispondi STOP per non ricevere più offerte." } ``` **DA NON FARE** ```json theme={null} { "type": "FOOTER", "text": "Sent to {{1}} on {{2}}" } ``` Documentazione Meta: [Componenti dei modelli — footer](https://developers.facebook.com/docs/whatsapp/business-management-api/message-templates/creating-templates#components). *** ## Set di regex di riferimento rapido Se stai scrivendo il tuo validatore o degli script per controlli in blocco, le regex canoniche sono: ```js theme={null} const PLACEHOLDER = /\{\{(\d+)\}\}/g; const adjacentVars = /\{\{\d+\}\}[^A-Za-zÀ-ÿ0-9]{0,3}\{\{\d+\}\}/; const startsWithVar = /^\s*\{\{\d+\}\}/; const endsWithVar = /\{\{\d+\}\}\s*[.!?]*\s*$/; const bareNumberExample = /^[\d\s.,%$€£¥+\-]+$/; const nameRule = /^[a-z][a-z0-9_]{0,511}$/; const langRule = /^[a-z]{2}(_[A-Z]{2})?$/; const dynamicUrl = /^https?:\/\/[^{}\s]+?(\{\{1\}\})?$/; ``` ## Vedi anche * [Il tuo primo modello](/it/getting-started/first-template) — guida passo passo end-to-end. * [Modelli di marketing](/it/whatsapp/marketing-templates) — regole specifiche per categoria e opt-out. * [Endpoint API dei modelli](/it/api-reference/template-endpoints) — invio programmatico.