Vai al contenuto principale

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:
{
  "name": "welcome_user",
  "language": "it_IT",
  "content": "Ciao {{name}}! Benvenuto in {{company}}. Come possiamo aiutarti oggi?",
  "variables": ["name", "company"],
  "category": "UTILITY"
}
Esempio Creazione:
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:
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:
const templates = await loviService.getTemplates();
// Restituisce array di template con stato, lingua, ecc.
Filtro per Lingua:
const italianTemplates = await loviService.getTemplates({
  language: "it_IT"
});
Template per Nome:
const template = await loviService.getTemplateByName("welcome_user", "it_IT");
// Restituisce dettagli completi del template

Aggiornamento Template

Modifica Contenuto:
await loviService.updateTemplate("welcome_user", {
  content: "Benvenuto {{name}}! Siamo felici di averti con noi.",
  variables: ["name"]
});
Cambio Lingua:
await loviService.updateTemplate("welcome_user", {
  language: "it_IT"
});

Eliminazione Template

Rimuovi Template:
await loviService.deleteTemplate("old_template");
// Nota: Solo template non utilizzati possono essere eliminati

โœ… Processo di Approvazione

Stati Template

StatoDescrizioneAzioni Disponibili
draftTemplate in bozzaModifica, invio per approvazione
pendingIn attesa di approvazioneModifica, controllo stato
approvedApprovato e utilizzabileUtilizzo in notifiche
rejectedRespintoModifica e reinvio

Invio per Approvazione

Invia Template:
await loviService.submitForApproval("template_name");
// Il template passa da draft/pending ad approved/rejected
Controllo Stato:
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:
await loviService.sendNotification({
  contact: { number: "34666033135" },
  template: "welcome_user",
  variables: {
    name: "Mario",
    company: "TechCorp"
  }
});

Programmazione Notifiche

Invio Programmato:
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:
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:
{
  "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:
{
  "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:
await loviService.createTemplate({
  name: "welcome_user",
  language: "it_IT",
  content: "Ciao {{name}}! Benvenuto in {{company}}."
});
Template Spagnolo:
await loviService.createTemplate({
  name: "welcome_user", 
  language: "es_ES",
  content: "ยกHola {{name}}! Bienvenido a {{company}}."
});

Selezione Automatica Lingua

Basata sul Contatto:
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:
const stats = await loviService.getTemplateStats("welcome_user");
// Restituisce: consegne, aperture, clic, ecc.
Report per Periodo:
const report = await loviService.getTemplateReport({
  template: "welcome_user",
  start_date: "2024-01-01",
  end_date: "2024-01-31"
});

Ottimizzazione Template

A/B Testing:
// 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:
// โœ… Buoni nomi
"welcome_user"
"order_confirmation" 
"appointment_reminder"

// โŒ Nomi da evitare  
"template1"
"new_template_2024"
"test"
Contenuto Template:
// โœ… 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:
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.