UC-013 — Ciclo di Vita dei Template WhatsApp

Campo	Valore
ID	UC-013
Obiettivo	Gestire il ciclo completo dei template WhatsApp: creazione, approvazione Meta, invio, modifica, eliminazione
Canale	WhatsApp
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	25 minuti
API coinvolte	`POST /api/message-server/whatsapp/templates`, `GET /whatsapp/templates`, `PATCH /whatsapp/templates/{id}`, `DELETE /whatsapp/templates/{id}`, `POST /api/message-server/whatsapp/send`

Scenari reali

TechStore — Template di benvenuto: Il team CRM crea un template per accogliere i nuovi clienti con un messaggio personalizzato, codice sconto e pulsanti di azione.
FashionOutlet — Promo marketing con link tracciati: Template promozionale con link cliccabili monitorati per misurare le conversioni della campagna Black Friday.
Studio Dentistico Bianchi — Promemoria appuntamento con pulsanti: Template UTILITY con pulsanti per confermare, riprogrammare o chiamare direttamente lo studio.

Ciclo di vita del template

:::warning Tempi di approvazione Meta L'approvazione da parte di Meta puo' richiedere da pochi minuti fino a 24 ore. Pianifica la creazione dei template con anticipo rispetto alla campagna. :::

Guida passo-passo

Step 1 — Creare un template

Crea un template di benvenuto con header testuale, body con placeholders, footer e pulsanti:

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "benvenuto_nuovo_cliente",
    "lang": "it",
    "category": "MARKETING",
    "headerText": "Benvenuto in TechStore!",
    "body": "Ciao {firstName}, siamo felici di averti con noi! Scopri le offerte riservate ai nuovi clienti e approfitta del codice sconto {codiceSconto} valido fino al {dataScadenza}.",
    "footer": "TechStore - Tecnologia per tutti",
    "buttons": [
      {
        "type": "URL",
        "text": "Vai alle offerte",
        "url": "https://techstore.it/offerte-benvenuto"
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Chiamaci",
        "phoneNumber": "+390212345678"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Non mi interessa"
      }
    ]
  }'

Categorie disponibili:

Categoria	Quando usarla	Esempi
`MARKETING`	Promozioni, offerte, newsletter	Saldi, nuovi prodotti, eventi
`UTILITY`	Comunicazioni transazionali	Conferma ordine, tracking, promemoria
`AUTHENTICATION`	Verifica identita	OTP, codici di verifica

Step 1b — Template con header immagine e link tracciati

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_primavera_2026",
    "lang": "it",
    "category": "MARKETING",
    "headerFormat": "IMAGE",
    "headerMediaUrl": "https://cdn.techstore.it/img/promo-primavera.jpg",
    "body": "Ciao {firstName}, i saldi di primavera sono arrivati! Fino al 30% di sconto su tutta la collezione. Clicca qui {shortLinkT1} per scoprire le offerte.",
    "footer": "Offerta valida fino al 30 aprile 2026",
    "placeholderFields": {
      "WHATSAPP": {
        "shortLinkT1": "https://techstore.it/saldi-primavera"
      }
    }
  }'

:::tip Link tracciati Il placeholder {shortLinkT1} nel body viene automaticamente sostituito con un link breve monitorato. Definisci l'URL di destinazione in placeholderFields. Per tracciare i click sui pulsanti URL, aggiungi "trackButtonLinks": true. :::

Step 1c — Template promemoria con pulsanti

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promemoria_appuntamento",
    "lang": "it",
    "category": "UTILITY",
    "headerText": "Promemoria appuntamento",
    "body": "Gentile {firstName}, le ricordiamo il suo appuntamento del {dataAppuntamento} alle ore {oraAppuntamento} presso {nomeStudio}, {indirizzo}.",
    "footer": "Per modifiche, contattaci almeno 24h prima",
    "buttons": [
      {
        "type": "QUICK_REPLY",
        "text": "Confermo"
      },
      {
        "type": "QUICK_REPLY",
        "text": "Devo spostare"
      },
      {
        "type": "PHONE_NUMBER",
        "text": "Chiama lo studio",
        "phoneNumber": "+390276543210"
      }
    ]
  }'

Step 2 — Attendere l'approvazione Meta

Dopo la creazione, il template entra in stato PENDING. Meta lo esamina per verificare la conformita alle sue policy.

Possibili stati:

Status	Significato
`PENDING`	In attesa di review da parte di Meta
`APPROVED`	Approvato, disponibile per l'invio
`REJECTED`	Rifiutato (controlla le linee guida Meta)
`PAUSED`	Messo in pausa da Meta
`DISABLED`	Disabilitato

Step 3 — Verificare lo stato del template

Controlla periodicamente lo stato:

curl -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates?status=PENDING&phoneNumberId=5&page=0&size=20" \
  -H "X-Api-Key: YOUR_API_KEY"

Per i dettagli di un template specifico:

curl -X GET "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY"

Parametro filtro	Descrizione
`category`	`MARKETING`, `UTILITY`, `AUTHENTICATION`
`status`	`APPROVED`, `PENDING`, `REJECTED`, `PAUSED`, `DISABLED`
`phoneNumberId`	Filtra per numero associato
`page`	Numero pagina (0-based)
`size`	Elementi per pagina

Step 4 — Inviare un messaggio con il template approvato

Una volta che lo status e' APPROVED, usa il template per inviare:

curl -X POST "https://lora-api.agiletelecom.com/api/message-server/whatsapp/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "phoneNumberId": 5,
    "template": {
      "id": 142,
      "mediaUrl": "https://cdn.techstore.it/img/promo-primavera.jpg"
    },
    "placeholders": {
      "firstName": "Marco",
      "codiceSconto": "SPRING20",
      "dataScadenza": "30 aprile 2026"
    },
    "enableNotification": true,
    "campaignId": "promo-primavera-2026"
  }'

Risposta:

{
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "simulation": false,
  "results": {
    "whatsapp": {
      "accepted": true
    },
    "rcs": null,
    "sms": null
  }
}

:::info Template con link tracciati nei pulsanti Per i template con pulsanti URL e tracking attivo, aggiungi "trackButtonLinks": true alla creazione del template. Il sistema generera' automaticamente un link tracciato per ogni pulsante URL. :::

Step 5 — Aggiornare un template

Modifica un template esistente con PATCH. Il template tornera' in stato PENDING per una nuova revisione Meta:

curl -X PATCH "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "body": "Ciao {firstName}, i super saldi di primavera sono arrivati! Fino al 40% di sconto su tutta la collezione. Non perdere questa occasione!",
    "footer": "Offerta valida fino al 15 maggio 2026"
  }'

:::warning Re-approvazione Qualsiasi modifica al template lo riporta allo stato PENDING. Dovrai attendere una nuova approvazione da parte di Meta prima di poterlo riutilizzare. Pianifica le modifiche con anticipo. :::

Step 6 — Eliminare un template

Quando un template non serve più':

curl -X DELETE "https://lora-api.agiletelecom.com/api/message-server/whatsapp/templates/142" \
  -H "X-Api-Key: YOUR_API_KEY"

Campi del template

Campo	Tipo	Obbligatorio	Descrizione
`name`	`string`	Si	Nome template (snake_case, minuscolo, numeri e underscore)
`lang`	`string`	Si	Codice lingua (`it`, `en`, `es`, ecc.)
`category`	`string`	Si	`MARKETING`, `UTILITY`, `AUTHENTICATION`
`body`	`string`	Si	Testo con placeholders `{nomeCampo}`
`headerText`	`string`	No	Testo header (esclusivo con `headerFormat`)
`headerFormat`	`string`	No	Header media: `IMAGE`, `VIDEO`, `DOCUMENT`
`headerMediaUrl`	`string`	No	URL media per l'header
`footer`	`string`	No	Testo footer
`buttons`	`array`	No	Pulsanti interattivi
`placeholderFields`	`object`	No	Definizione link tracciati
`trackButtonLinks`	`boolean`	No	Traccia click su pulsanti URL

Tipi di pulsante

Tipo	Campi	Descrizione
`URL`	`text`, `url`	Apre un URL nel browser
`PHONE_NUMBER`	`text`, `phoneNumber`	Avvia una chiamata
`QUICK_REPLY`	`text`	Risposta rapida predefinita

Dietro le quinte

Il flusso di approvazione dei template WhatsApp coinvolge sia la piattaforma Qlara che Meta:

Creazione -- Il template viene inviato a Meta tramite la Business API. Meta lo prende in carico per la revisione.
Review Meta -- Meta verifica che il template rispetti le sue policy (niente contenuti ingannevoli, spam, o violazioni dei termini). La review puo' essere automatica (minuti) o manuale (fino a 24h).
Notifica stato -- La piattaforma Qlara riceve l'aggiornamento di stato da Meta e lo rende disponibile tramite l'API.
Invio -- Quando il template e' APPROVED, puoi usarlo per iniziare conversazioni o inviare messaggi fuori dalla finestra 24h. I placeholders vengono sostituiti al momento dell'invio.
Aggiornamento -- Un PATCH modifica il template e lo risottomette a Meta. Lo stato torna PENDING fino alla nuova approvazione.
Regola del nome -- Il campo name deve essere in snake_case con solo lettere minuscole, numeri e underscore. Questo e' un requisito Meta.
Associazione numero -- Il phoneNumberId nella query string della creazione associa il template a un numero WhatsApp Business specifico. Usa GET /whatsapp/phone-numbers per ottenere l'elenco dei numeri disponibili.

Prossimi passi

Guida WhatsApp Templates -- Riferimento completo sui template WhatsApp
Guida WhatsApp API -- Invio messaggi e gestione numeri
UC-012: RCS Template Workflow -- Confronta con il flusso template RCS (senza approvazione esterna)
UC-009: Two-Way Conversation -- Gestisci le risposte ai template inviati
UC-010: Scheduled Messages -- Programma l'invio di template WhatsApp

Scenari reali​

Ciclo di vita del template​

Guida passo-passo​

Step 1 — Creare un template​

Step 1b — Template con header immagine e link tracciati​

Step 1c — Template promemoria con pulsanti​

Step 2 — Attendere l'approvazione Meta​

Step 3 — Verificare lo stato del template​

Step 4 — Inviare un messaggio con il template approvato​

Step 5 — Aggiornare un template​

Step 6 — Eliminare un template​

Campi del template​

Tipi di pulsante​

Prossimi passi​