UC-030 — Template Lifecycle Completo (Test, Campagna, Analisi)

Campo	Valore
ID	UC-030
Obiettivo	Gestire il ciclo di vita completo di un template WhatsApp: creazione, approvazione, test, campagna e analisi
Canale	WhatsApp
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	30 minuti (esclusi tempi di approvazione Meta)
API coinvolte	POST /api/message-server/whatsapp/templates, GET /api/message-server/whatsapp/templates/{templateId}, POST /api/message-server/whatsapp/send, POST /api/partner-gateway/v1/campaigns, POST /api/partner-gateway/v1/campaigns/{id}/calculateGoal, PUT /api/partner-gateway/v1/campaigns/{id}/confirm, GET /api/partner-gateway/v1/campaigns/{id}, POST /api/partner-gateway/v1/exports/delivery-reports, GET /api/partner-gateway/v1/exports/{exportId}

Scenari reali

• FashionOutlet — Lancio nuova promozione: Il team marketing crea un template WhatsApp per i saldi estivi, lo testa in simulazione, poi lo usa per una campagna su 20.000 clienti VIP. A campagna conclusa, esporta i risultati per calcolare il ROI.
• ClinicaSalute — Onboarding template per nuovo servizio: La clinica crea un template per promuovere un nuovo servizio di telemedicina. Dopo l'approvazione Meta, lo testa su un gruppo ristretto, verifica la resa visiva e poi lancia la campagna.
• BancaAdriatica — A/B testing template: Il team CRM crea due varianti di template per la promozione di un prestito personale. Testa entrambe su campioni ridotti, confronta i tassi di consegna e lettura, poi usa la variante vincente per l'invio massivo.

Use case composito

Questo UC combina i flussi di UC-013 — WhatsApp Template Workflow, UC-006 — Campagna Bulk e UC-011 — Export Delivery Reports in un ciclo di vita completo.

Flusso del lifecycle

Il diagramma illustra il ciclo completo: dalla creazione del template alla campagna, fino all'analisi dei risultati per iterare e migliorare.

Step 1 — Crea il template WhatsApp

Sottometti il template a Meta per l'approvazione con la WhatsApp API. Il parametro di query phoneNumberId lo associa al tuo numero WhatsApp Business, e {firstName} è una variabile valorizzata al momento dell'invio:

curl -X POST "https://api.qlara.ai/api/message-server/whatsapp/templates?phoneNumberId=5" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_estate_2026",
    "lang": "it",
    "category": "MARKETING",
    "headerFormat": "IMAGE",
    "headerMediaUrl": "https://fashionoutlet.it/media/saldi-estate-2026.jpg",
    "body": "Ciao {firstName}! Saldi estivi FashionOutlet: fino al 40% di sconto. Offerta valida fino al 30 giugno!",
    "footer": "FashionOutlet - Moda per tutti",
    "buttons": [
      { "type": "URL", "text": "Scopri le offerte", "url": "https://fashionoutlet.it/saldi?ref=campaign_estate_2026" },
      { "type": "QUICK_REPLY", "text": "Non mi interessa" }
    ]
  }'

Response — Template sottomesso

{ "id": 187, "name": "promo_estate_2026", "lang": "it", "category": "MARKETING", "status": "PENDING" }

Tempi di approvazione Meta

L'approvazione dei template da parte di Meta richiede tipicamente da poche ore a 24 ore. I template MARKETING hanno tempi più lunghi rispetto a quelli UTILITY o AUTHENTICATION. Configura un webhook per ricevere la notifica di approvazione o rifiuto.

Step 2 — Attendi l'approvazione e verifica lo stato

Controlla periodicamente lo stato del template:

curl -X GET "https://api.qlara.ai/api/message-server/whatsapp/templates/187" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Template approvato

{ "id": 187, "name": "promo_estate_2026", "lang": "it", "category": "MARKETING", "status": "APPROVED" }

Dietro le quinte — Quality Score e limiti

1. Quality Score: GREEN/YELLOW/RED basato sulle interazioni utenti. Un punteggio basso limita il volume.
2. Tier di invio: Da tier 1 (1K conversazioni/giorno) a tier 4 (illimitato), cresce con la qualita.
3. Rifiuto: Motivi comuni — linguaggio aggressivo, mancanza opt-out, placeholder impropri. Modifica e risottometti.

Step 3 — Testa il template in simulazione

Prima della campagna, verifica il template con un invio in simulazione ("simulation": true):

curl -X POST https://api.qlara.ai/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "phoneNumberId": 5,
    "simulation": true,
    "template": {
      "id": 187,
      "mediaUrl": "https://fashionoutlet.it/media/saldi-estate-2026.jpg"
    },
    "placeholders": {
      "firstName": "Marco"
    }
  }'

Response — Simulazione riuscita

{
  "messageId": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
  "simulation": true,
  "results": { "whatsapp": { "accepted": true, "reasons": [] } }
}

Invio di test reale

Dopo la simulazione, invia un test reale al tuo numero personale (senza "simulation": true) per verificare la resa visiva su dispositivo.

Step 4 — Crea e lancia la campagna

Con il template testato, crea la campagna sullo stesso numero WhatsApp e conferma l'invio. Le variabili del template vengono valorizzate dai dati di ciascun contatto della lista:

curl -X POST "https://api.qlara.ai/api/partner-gateway/v1/campaigns" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saldi Estate 2026 - WhatsApp VIP",
    "sendingMode": "WHATSAPP",
    "destinationType": 0,
    "contactListIds": [2208],
    "whatsappPhoneNumberId": 5,
    "whatsappTemplateId": 187,
    "readyToSend": true
  }'

Response

{
  "id": 4630,
  "name": "Saldi Estate 2026 - WhatsApp VIP",
  "status": "READY_TO_SEND",
  "sendingMode": "WHATSAPP",
  "destinationType": 0,
  "contactListIds": [2208],
  "whatsappPhoneNumberId": 5,
  "whatsappTemplateId": 187,
  "readyToSend": true
}

Ricalcola il costo con POST /campaigns/{id}/calculateGoal, poi conferma l'invio con PUT /campaigns/{id}/confirm (202 Accepted).

Step 5 — Monitora e esporta

Monitora con GET /campaigns/{id} fino a status: "ENDED", poi esporta il report con POST /exports/delivery-reports (vedi UC-029 per il flusso completo di export).

{
  "id": 4630,
  "name": "Saldi Estate 2026 - WhatsApp VIP",
  "status": "ENDED",
  "sendingMode": "WHATSAPP",
  "totalDestinations": 20150,
  "totalSent": 20150,
  "totalSuccess": 18935,
  "totalFailed": 695,
  "totalRead": 12480,
  "waSent": 20150,
  "waPending": 520,
  "waSuccess": 18935,
  "waFailed": 695,
  "waRead": 12480
}

18.935 consegnati su 20.150 corrispondono a un tasso di consegna del 93,97%; 12.480 letti su 18.935 consegnati a un tasso di lettura del 65,91%.

Risultato atteso

Step	Azione	Risultato
1	POST /whatsapp/templates	Template sottomesso, status: "PENDING"
2	GET /whatsapp/templates/{id}	status: "APPROVED"
3	POST /whatsapp/send (simulation)	simulation: true, accepted: true
4	POST /campaigns + calculateGoal + PUT /confirm	Campagna creata e confermata (202 Accepted)
5	GET /campaigns/{id} + export	status: "ENDED", 93,97% consegnati, CSV scaricabile

Esempio completo end-to-end

#!/bin/bash
API_KEY="YOUR_API_KEY"
PG="https://api.qlara.ai/api/partner-gateway/v1"
MS="https://api.qlara.ai/api/message-server"

# 1. Crea template
TPL_ID=$(curl -s -X POST "${MS}/whatsapp/templates?phoneNumberId=5" -H "X-Api-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"promo_estate_2026","lang":"it","category":"MARKETING","body":"Ciao {firstName}! Saldi estivi: -40% fino al 30 giugno!"}' | jq -r '.id')

# 2. Attendi approvazione
while true; do
  S=$(curl -s "${MS}/whatsapp/templates/${TPL_ID}" -H "X-Api-Key: ${API_KEY}" | jq -r '.status')
  [[ "$S" == "APPROVED" ]] && break; [[ "$S" == "REJECTED" ]] && exit 1; sleep 300
done

# 3. Test simulazione
curl -s -X POST "${MS}/whatsapp/send" -H "Content-Type: application/json" -H "X-Api-Key: ${API_KEY}" \
  -d '{"destination":"+393471234567","phoneNumberId":5,"simulation":true,"template":{"id":'"${TPL_ID}"'},"placeholders":{"firstName":"Marco"}}' | jq .

# 4. Campagna → 5. Monitora → Export (vedi UC-029 per il flusso export completo)
CMP_ID=$(curl -s -X POST "${PG}/campaigns" -H "X-Api-Key: ${API_KEY}" -H "Content-Type: application/json" \
  -d '{"name":"Saldi Estate 2026","sendingMode":"WHATSAPP","destinationType":0,"contactListIds":[2208],"whatsappPhoneNumberId":5,"whatsappTemplateId":'"${TPL_ID}"',"readyToSend":true}' | jq -r '.id')
curl -s -X POST "${PG}/campaigns/${CMP_ID}/calculateGoal" -H "X-Api-Key: ${API_KEY}" > /dev/null
curl -s -X PUT "${PG}/campaigns/${CMP_ID}/confirm" -H "X-Api-Key: ${API_KEY}" > /dev/null

Varianti

A/B Testing con due template

Crea due varianti (es. tono urgente vs amichevole), attendi l'approvazione di entrambe, poi lancia due campagne su segmenti diversi della stessa lista. Confronta totalSuccess e totalRead rispetto a totalSent delle due campagne con GET /campaigns/{id}, oppure nei rispettivi report.

Template con bottone di opt-out tracciato

Il bottone Quick Reply "Non mi interessa" genera un webhook INBOUND con il testo del bottone, che puoi usare per aggiornare le preferenze del contatto (vedi UC-028).

Errori comuni

Template rifiutato da Meta

{ "id": 187, "name": "promo_estate_2026", "lang": "it", "category": "MARKETING", "status": "REJECTED" }

Soluzione: La risposta non riporta il motivo. Motivi comuni: linguaggio aggressivo, promesse irrealistiche, mancanza di identita del mittente. Modifica il template con PATCH /api/message-server/whatsapp/templates/{templateId}: torna in revisione.

Campagna con template non approvato

{ "status": "fail", "data": { "error": "Template 'promo_estate_2026' is not in APPROVED status" } }

Soluzione: Solo i template con status: "APPROVED" possono essere usati nelle campagne. Verifica lo stato prima di creare la campagna.

Prossimi passi

• UC-013 — WhatsApp Template Workflow: Approfondisci la gestione dei template
• UC-006 — Campagna Bulk SMS: Dettagli sulla creazione di campagne
• UC-011 — Export Delivery Reports: Approfondisci gli export asincroni
• UC-029 — Report Campagna Completo: Analisi dettagliata dei risultati campagna

Riferimenti

• API WhatsApp Templates — Documentazione endpoint
• API WhatsApp Send — Documentazione endpoint
• API Campaigns — Documentazione endpoint
• API Exports — Documentazione endpoint
• Meta WhatsApp Business Platform — Template Guidelines