> ## 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.
# Il tuo primo modello WhatsApp
> Crea, valida e invia il tuo primo modello di messaggio WhatsApp in Switchbord — dall'editor vuoto all'approvazione di Meta.
Questa guida ti accompagna da un editor di modelli vuoto a un modello WhatsApp approvato in circa quindici minuti. Ti serve solo un WhatsApp Business Account (WABA) collegato e un operatore con accesso alle impostazioni.
## Cos'è un modello WhatsApp
Un modello WhatsApp è una definizione di messaggio riutilizzabile che Meta pre-approva prima che tu possa inviarla. Ogni **messaggio in uscita avviato dal business** — una conferma di prenotazione, una notifica di fattura, una promozione stagionale — deve fare riferimento a un modello approvato. Il modello contiene la struttura (testo, bottoni, media dell'header) e il tuo codice a runtime inserisce i placeholder `{{1}}`, `{{2}}` per ogni destinatario.
I modelli sono l'unico modo per ricontattare un contatto fuori dalla finestra di servizio clienti di 24 ore, quindi una libreria pulita e approvata è la base di ogni campagna e journey che eseguirai su Switchbord.
## Perché i modelli richiedono l'approvazione di Meta
WhatsApp è un canale basato sul consenso. Per proteggere gli utenti dallo spam, Meta richiede che ogni modello business passi attraverso una pipeline di pre-approvazione che verifica:
* **Struttura** — i placeholder sono ben formati, gli esempi sono realistici, il corpo non inizia né termina con una variabile, i bottoni sono nei limiti.
* **Corrispondenza della categoria** — il contenuto corrisponde realmente a `UTILITY`, `MARKETING` o `AUTHENTICATION`.
* **Policy** — nessun settore vietato, nessuna affermazione ingannevole, opt-out presente sul marketing.
Non puoi mettere in produzione un modello che non ha superato questa revisione. L'editor di Switchbord esegue localmente gli stessi controlli strutturali prima dell'invio, così la maggior parte delle violazioni viene individuata prima che Meta veda il payload. Consulta il [Riferimento alle regole dei modelli](/it/whatsapp/template-rules) per l'elenco completo.
## Passo dopo passo
### 1. Apri l'editor dei modelli
Dalla barra laterale sinistra, clicca **Modelli**. Vedrai la libreria dei modelli già inviati da questa area di lavoro, filtrabile per stato (`draft`, `pending_approval`, `approved`, `rejected`).
Clicca **Nuovo modello** in alto a destra. Si apre un editor vuoto con quattro pannelli: metadati, componenti, anteprima e validazione.
### 2. Scegli una categoria
La categoria determina la fatturazione, la tolleranza in fase di approvazione e quali componenti puoi usare.
| Categoria | Da usare quando | Livello di fatturazione |
| ---------------- | ------------------------------------------------------------ | ----------------------- |
| `UTILITY` | Aggiornamenti su ordini, prenotazioni, fatture, appuntamenti | Più basso |
| `MARKETING` | Promozioni, campagne, riattivazione | Più alto |
| `AUTHENTICATION` | Codici usa e getta, MFA | Fisso per regione |
Scegli quella che corrisponde all'**intento** del messaggio, non al contenuto. Scrivere "20% di sconto" in un modello `UTILITY` verrà rifiutato oppure ricategorizzato silenziosamente da Meta. Consulta [Modelli marketing](/it/whatsapp/marketing-templates) per l'albero decisionale completo.
Lascia abilitato **Allow category change** sulle bozze marketing. Permette a Meta di correggere automaticamente la categoria durante la revisione invece di rifiutare direttamente.
### 3. Scrivi il corpo con le variabili
Componi il testo del corpo e usa `{{1}}`, `{{2}}`, `{{3}}` per le sostituzioni a runtime.
```text Example body theme={null}
Ciao {{1}}, la tua prenotazione per {{2}} è confermata. Il codice è {{3}}.
```
Tre regole da interiorizzare dal primo giorno:
1. **Non iniziare né terminare il corpo con un placeholder.** Aggiungi un saluto all'inizio e un contesto con punto finale alla fine.
2. **Non inserire due placeholder adiacenti** con solo spazi o punteggiatura tra loro (`{{1}}, {{2}}`). Inserisci almeno una parola tra di essi.
3. **Numera in sequenza** partendo da `{{1}}`. Nessun salto, nessuna ripetizione.
Il pannello di validazione live evidenzia le violazioni in linea e collega alla regola esatta.
### 4. Aggiungi esempi per ogni variabile
Ogni `{{n}}` ha bisogno di un valore di esempio realistico. Meta usa questi valori per valutare se il modello corrisponde alla categoria e per rendere un'anteprima durante la revisione.
```json Example body_text payload theme={null}
"example": {
"body_text": [["Marco Rossi", "Roma — Hotel Colosseo", "GBV-2025-0042"]]
}
```
Evita:
* Numeri nudi (`"20"`, `"5"`)
* Simboli singoli (`"%"`, `"€"`)
* Il testo letterale del placeholder (`"{{1}}"`)
* URL se il corpo non ne contiene
Includi l'unità direttamente nell'esempio — scrivi `"20%"` per il frammento del corpo `"sconto del {{1}}"`, non solo `"20"`.
### 5. Invia
Clicca **Submit for approval**. Switchbord esegue la validazione finale lato client, poi effettua una `POST` all'endpoint `/message_templates` di Meta. In caso di successo, lo stato locale passa a `pending_approval` e il modello scompare dal filtro delle bozze.
## Cosa succede dopo
La revisione di Meta è quasi sempre rapida:
* **Pochi minuti** per i modelli `UTILITY` ben formati che corrispondono alla categoria.
* **Un'ora o due** per i modelli `MARKETING` che passano per la revisione dei contenuti.
* **Fino a 24 ore** sotto carico o quando interviene un revisore umano.
Non serve fare polling. Il nostro gestore dei webhook ascolta l'evento `message_template_status_update` e imposta la riga su `approved`, `rejected`, oppure registra una migrazione di categoria. L'elenco Modelli si aggiorna in tempo reale tramite Supabase Realtime.
## Se il modello viene rifiutato
Un rifiuto non è un fallimento — è solo una voce di checklist. Switchbord archivia il motivo leggibile fornito da Meta nella colonna `rejection_reason` e lo mostra in evidenza in alto nell'editor.
Apri il modello rifiutato. Il banner rosso mostra l'`error_user_msg` di Meta parola per parola — ad esempio *"Variable parameters cannot be next to each other."*
Ogni messaggio corrisponde a una regola sulla pagina [Regole dei modelli](/it/whatsapp/template-rules). Il codice di errore del validatore si trova nell'ancora dell'URL.
Duplica il modello rifiutato (l'originale è bloccato), applica la correzione e clicca di nuovo **Submit for approval**. Non c'è penalità per il reinvio — Meta applica un rate limit di 100 modelli/ora per WABA, che è più che sufficiente.
Se lo stesso modello viene rifiutato due volte per motivi diversi, di solito significa che la prima correzione ha mascherato una seconda violazione. Esegui **Validate** (linter dry-run, nessuna chiamata a Meta) per individuare entrambe prima di reinviare.
## Prossimi passi
* [Riferimento alle regole dei modelli](/it/whatsapp/template-rules) — ogni regola del validatore, con esempi corretti e da evitare.
* [Modelli marketing](/it/whatsapp/marketing-templates) — approfondimento sulla categoria MARKETING, opt-out e migrazione di categoria.
* [Endpoint API dei modelli](/it/api-reference/template-endpoints) — automatizza la gestione dei modelli dai tuoi script.