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/partner-gateway/v1/whatsapp/templates, POST /api/message-server/whatsapp/send, POST /api/partner-gateway/v1/campaigns, PUT /api/partner-gateway/v1/campaigns/{id}/confirm, 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.

:::info 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:

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/whatsapp/templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_estate_2026",
    "language": "it",
    "category": "MARKETING",
    "components": [
      { "type": "HEADER", "format": "IMAGE",
        "example": { "header_handle": ["https://fashionoutlet.it/media/saldi-estate-2026.jpg"] } },
      { "type": "BODY",
        "text": "Ciao {{1}}! Saldi estivi FashionOutlet: fino al {{2}}% di sconto. Offerta valida fino al {{3}}!",
        "example": { "body_text": [["Marco", "40", "30 giugno"]] } },
      { "type": "FOOTER", "text": "FashionOutlet - Moda per tutti" },
      { "type": "BUTTONS", "buttons": [
        { "type": "URL", "text": "Scopri le offerte", "url": "https://fashionoutlet.it/saldi?ref={{1}}", "example": ["campaign_estate_2026"] },
        { "type": "QUICK_REPLY", "text": "Non mi interessa" }
      ]}
    ]
  }'

Response — Template sottomesso

{ "templateId": "tpl_8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d", "name": "promo_estate_2026", "status": "PENDING", "category": "MARKETING" }

:::info 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://lora-api.agiletelecom.com/api/partner-gateway/v1/whatsapp/templates/tpl_8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Template approvato

{ "templateId": "tpl_8a9b0c1d-2e3f-4a5b-6c7d-8e9f0a1b2c3d", "status": "APPROVED", "qualityScore": "GREEN", "approvedAt": "2026-04-09T18:30:00+02:00" }

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://lora-api.agiletelecom.com/api/message-server/whatsapp/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393471234567",
    "sender": "+393801234567",
    "simulation": true,
    "content": {
      "templateName": "promo_estate_2026",
      "language": "it",
      "components": [
        { "type": "body", "parameters": [
          { "type": "text", "text": "Marco" },
          { "type": "text", "text": "40" },
          { "type": "text", "text": "30 giugno" }
        ]}
      ]
    }
  }'

Response — Simulazione riuscita

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

:::tip 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 e conferma l'invio:

curl -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Saldi Estate 2026 - WhatsApp VIP",
    "channel": "WHATSAPP",
    "sender": "+393801234567",
    "contactListId": "lst_clienti_vip_2026",
    "whatsappTemplate": {
      "templateName": "promo_estate_2026",
      "language": "it",
      "bodyParameters": ["firstName", "discountPercent", "expiryDate"]
    }
  }'

Response

{ "id": "cmp_2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f", "status": "DRAFT", "totalContacts": 20150 }

Conferma l'invio con PUT /campaigns/{id}/confirm.

Step 5 — Monitora e esporta

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

{
  "campaignId": "cmp_2c3d4e5f-6a7b-8c9d-0e1f-2a3b4c5d6e7f",
  "status": "COMPLETED",
  "stats": {
    "totalMessages": 20150, "delivered": 18935, "read": 12480,
    "failed": 695, "deliveryRate": 93.97, "readRate": 65.91,
    "totalCost": 1612.00
  }
}

Risultato atteso

Step	Azione	Risultato
1	POST /whatsapp/templates	Template sottomesso, status: "PENDING"
2	GET /whatsapp/templates/{id}	status: "APPROVED", qualityScore: "GREEN"
3	POST /whatsapp/send (simulation)	simulation: true, accepted: true
4	POST /campaigns + PUT /confirm	Campagna creata e confermata
5	GET /campaigns/{id}/stats + export	deliveryRate: 93.97%, CSV scaricabile

Esempio completo end-to-end

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

# 1. Crea template
TPL_ID=$(curl -s -X POST "${PG}/whatsapp/templates" -H "X-Api-Key: ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"name":"promo_estate_2026","language":"it","category":"MARKETING","components":[{"type":"BODY","text":"Ciao {{1}}! Saldi: -{{2}}% fino al {{3}}!"}]}' | jq -r '.templateId')

# 2. Attendi approvazione
while true; do
  S=$(curl -s "${PG}/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","sender":"+393801234567","simulation":true,"content":{"templateName":"promo_estate_2026","language":"it","components":[{"type":"body","parameters":[{"type":"text","text":"Marco"},{"type":"text","text":"40"},{"type":"text","text":"30 giugno"}]}]}}' | 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","channel":"WHATSAPP","sender":"+393801234567","contactListId":"lst_clienti_vip_2026","whatsappTemplate":{"templateName":"promo_estate_2026","language":"it","bodyParameters":["firstName","discountPercent","expiryDate"]}}' | jq -r '.id')
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 deliveryRate e readRate 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

{ "templateId": "tpl_8a9b0c1d", "status": "REJECTED", "rejectionReason": "Template content violates WhatsApp Commerce Policy" }

Soluzione: Motivi comuni: linguaggio aggressivo, promesse irrealistiche, mancanza di identita del mittente. Modifica e risottometti.

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