> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lovi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Gestione Template

> Guida completa per creare, gestire e utilizzare template di messaggi

## Introduzione

I template sono componenti essenziali dell'API Lovi, permettendo di creare messaggi standardizzati e personalizzati per le comunicazioni WhatsApp. Questa guida copre tutte le operazioni relative alla gestione dei template.

## 📝 Creazione Template

### Template Base

**Struttura Template:**

```json theme={null}
{
  "name": "welcome_user",
  "language": "it_IT",
  "content": "Ciao {{name}}! Benvenuto in {{company}}. Come possiamo aiutarti oggi?",
  "variables": ["name", "company"],
  "category": "UTILITY"
}
```

**Esempio Creazione:**

```javascript theme={null}
const template = await loviService.createTemplate({
  name: "order_confirmation",
  language: "it_IT",
  content: "Grazie {{name}}! Il tuo ordine #{{order_id}} è stato confermato. Totale: €{{total}}",
  variables: ["name", "order_id", "total"],
  category: "UTILITY"
});
```

### Variabili Template

**Sintassi Variabili:**

```
Ciao {{name}}!

Il tuo appuntamento è confermato per il {{date}} alle {{time}}.

Servizi richiesti: {{services}}

Per qualsiasi modifica, contattaci al {{phone}}.

Grazie,
{{company}}
```

**Validazione Variabili:**

```javascript theme={null}
function validateTemplateVariables(content, providedVariables) {
  const requiredVars = extractVariables(content); // Estrae {{var}} dal contenuto
  const providedVars = Object.keys(providedVariables);
  
  const missing = requiredVars.filter(v => !providedVars.includes(v));
  const extra = providedVars.filter(v => !requiredVars.includes(v));
  
  if (missing.length > 0) {
    throw new Error(`Variabili mancanti: ${missing.join(', ')}`);
  }
  
  if (extra.length > 0) {
    console.warn(`Variabili extra fornite: ${extra.join(', ')}`);
  }
}
```

## 📋 Gestione Template

### Recupero Template

**Lista Tutti i Template:**

```javascript theme={null}
const templates = await loviService.getTemplates();
// Restituisce array di template con stato, lingua, ecc.
```

**Filtro per Lingua:**

```javascript theme={null}
const italianTemplates = await loviService.getTemplates({
  language: "it_IT"
});
```

**Template per Nome:**

```javascript theme={null}
const template = await loviService.getTemplateByName("welcome_user", "it_IT");
// Restituisce dettagli completi del template
```

### Aggiornamento Template

**Modifica Contenuto:**

```javascript theme={null}
await loviService.updateTemplate("welcome_user", {
  content: "Benvenuto {{name}}! Siamo felici di averti con noi.",
  variables: ["name"]
});
```

**Cambio Lingua:**

```javascript theme={null}
await loviService.updateTemplate("welcome_user", {
  language: "it_IT"
});
```

### Eliminazione Template

**Rimuovi Template:**

```javascript theme={null}
await loviService.deleteTemplate("old_template");
// Nota: Solo template non utilizzati possono essere eliminati
```

## ✅ Processo di Approvazione

### Stati Template

| Stato      | Descrizione               | Azioni Disponibili               |
| ---------- | ------------------------- | -------------------------------- |
| `draft`    | Template in bozza         | Modifica, invio per approvazione |
| `pending`  | In attesa di approvazione | Modifica, controllo stato        |
| `approved` | Approvato e utilizzabile  | Utilizzo in notifiche            |
| `rejected` | Respinto                  | Modifica e reinvio               |

### Invio per Approvazione

**Invia Template:**

```javascript theme={null}
await loviService.submitForApproval("template_name");
// Il template passa da draft/pending ad approved/rejected
```

**Controllo Stato:**

```javascript theme={null}
const status = await loviService.getTemplateStatus("template_name");
// Restituisce: { status: "approved", approved_at: "2024-01-15T10:30:00Z" }
```

## 🎯 Utilizzo Template

### Invio Notifica Semplice

**Con Template Approvato:**

```javascript theme={null}
await loviService.sendNotification({
  contact: { number: "34666033135" },
  template: "welcome_user",
  variables: {
    name: "Mario",
    company: "TechCorp"
  }
});
```

### Programmazione Notifiche

**Invio Programmato:**

```javascript theme={null}
await loviService.sendNotification({
  contact: { number: "34666033135" },
  template: "appointment_reminder",
  variables: {
    name: "Mario",
    date: "2024-12-25",
    time: "10:30"
  },
  datetime_sending: "2024-12-24T09:00:00Z" // 1 ora prima
});
```

### Template Multipli

**Invio Bulk:**

```javascript theme={null}
const notifications = [
  {
    contact: { number: "34666033136" },
    template: "welcome_user",
    variables: { name: "Luca", company: "TechCorp" }
  },
  {
    contact: { number: "34666033137" },
    template: "welcome_user", 
    variables: { name: "Anna", company: "TechCorp" }
  }
];

await loviService.sendBulkNotifications(notifications);
```

## 🏷️ Categorie Template

### Categorie Supportate

* **MARKETING**: Promozioni, annunci, offerte speciali
* **UTILITY**: Conferme, aggiornamenti, ricevute
* **AUTHENTICATION**: Codici verifica, sicurezza

### Linee Guida per Categoria

**Template Marketing:**

```json theme={null}
{
  "name": "special_offer",
  "content": "🎉 Offerta speciale per te {{name}}! Sconto {{discount}}% su tutti i prodotti fino al {{expiry_date}}.",
  "category": "MARKETING",
  "variables": ["name", "discount", "expiry_date"]
}
```

**Template Utility:**

```json theme={null}
{
  "name": "order_update",
  "content": "Il tuo ordine {{order_id}} è stato spedito. Numero tracking: {{tracking_number}}",
  "category": "UTILITY", 
  "variables": ["order_id", "tracking_number"]
}
```

## 🌍 Supporto Multilingua

### Template per Lingua

**Template Italiano:**

```javascript theme={null}
await loviService.createTemplate({
  name: "welcome_user",
  language: "it_IT",
  content: "Ciao {{name}}! Benvenuto in {{company}}."
});
```

**Template Spagnolo:**

```javascript theme={null}
await loviService.createTemplate({
  name: "welcome_user", 
  language: "es_ES",
  content: "¡Hola {{name}}! Bienvenido a {{company}}."
});
```

### Selezione Automatica Lingua

**Basata sul Contatto:**

```javascript theme={null}
await loviService.sendNotification({
  contact: { 
    number: "34666033135",
    language: "it_IT" // Se disponibile
  },
  template: "welcome_user",
  auto_language: true // Seleziona template basato sulla lingua del contatto
});
```

## 📊 Analisi Template

### Metriche Performance

**Statistiche Utilizzo:**

```javascript theme={null}
const stats = await loviService.getTemplateStats("welcome_user");
// Restituisce: consegne, aperture, clic, ecc.
```

**Report per Periodo:**

```javascript theme={null}
const report = await loviService.getTemplateReport({
  template: "welcome_user",
  start_date: "2024-01-01",
  end_date: "2024-01-31"
});
```

### Ottimizzazione Template

**A/B Testing:**

```javascript theme={null}
// Crea versioni alternative
await loviService.createTemplate({
  name: "welcome_a",
  content: "Benvenuto {{name}}! Scopri i nostri servizi."
});

await loviService.createTemplate({
  name: "welcome_b", 
  content: "Ciao {{name}}! Siamo felici di averti qui."
});

// Invia versioni alternate e confronta metriche
```

## ⚠️ Limitazioni e Considerazioni

### Limiti Template

* **Lunghezza Contenuto**: Max 1024 caratteri
* **Variabili**: Max 20 per template
* **Template per Account**: 100 attivi contemporaneamente
* **Rate Creazione**: 10 template al giorno

### Best Practice

**Nomi Template:**

```javascript theme={null}
// ✅ Buoni nomi
"welcome_user"
"order_confirmation" 
"appointment_reminder"

// ❌ Nomi da evitare  
"template1"
"new_template_2024"
"test"
```

**Contenuto Template:**

```javascript theme={null}
// ✅ Chiaro e conciso
"Ciao {{name}}, il tuo appuntamento è confermato per {{date}} alle {{time}}."

// ❌ Troppo lungo o confuso
"Gentile cliente {{name}}, siamo lieti di informarla che la sua prenotazione presso la nostra struttura per il servizio richiesto è stata correttamente registrata nel nostro sistema per la data del {{date}} con orario previsto delle ore {{time}}. La preghiamo di presentarsi 15 minuti prima dell'orario stabilito."
```

### Sicurezza

**Validazione Input:**

```javascript theme={null}
function sanitizeVariables(variables) {
  const sanitized = {};
  for (const [key, value] of Object.entries(variables)) {
    // Rimuovi caratteri potenzialmente pericolosi
    sanitized[key] = String(value).replace(/[<>]/g, '');
  }
  return sanitized;
}
```

I template sono fondamentali per comunicazioni WhatsApp efficaci e conformi. Segui queste linee guida per massimizzare l'impatto delle tue campagne di comunicazione.