UC-022 — Campagna Bulk WhatsApp Template

Campo	Valore
ID	UC-022
Obiettivo	Creare e inviare una campagna bulk WhatsApp con template approvati
Canale	WhatsApp
Complessità	⭐⭐ Intermedio
Tempo stimato	25 minuti
API coinvolte	`POST /api/partner-gateway/v1/campaigns`, `PUT /campaigns/{id}`, `POST /campaigns/{id}/calculateGoal`, `GET /campaigns/{id}/price`, `PUT /campaigns/{id}/confirm`

Scenari reali

ShopItalia — Notifica promozione WhatsApp: ShopItalia invia una promozione "Saldi estivi -50%" a 15.000 clienti tramite template WhatsApp con bottone "Vai allo shop" e immagine header.
BeautyBox — Coupon personalizzati: Invio massivo di coupon sconto personalizzati con nome cliente e codice univoco, tracciando l'apertura e il click sul link.
AssicuraSemplice — Remind scadenza polizza: Notifica automatica ai clienti con polizza in scadenza nei prossimi 30 giorni, con bottone per il rinnovo online.

Ciclo di vita della campagna WhatsApp

Il diagramma illustra il ciclo dalla bozza alla configurazione con template WhatsApp approvato da Meta, stima costo, conferma e monitoraggio delle metriche di consegna e lettura.

Prerequisiti

API Key attiva con permessi campagne e canale WhatsApp
Template WhatsApp approvato da Meta (vedi UC-013)
Numero WhatsApp Business verificato e attivo (vedi UC-025)
Lista contatti creata e popolata (vedi UC-007)

Step 1 — Crea la campagna in bozza

Crea una nuova campagna specificando il canale WhatsApp.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "Saldi Estivi 2026",
    "channel": "WHATSAPP",
    "description": "Promozione saldi estivi -50% con coupon personalizzato"
  }'

Response — Campagna creata

{
  "id": "camp-wa-2026-saldi-001",
  "name": "Saldi Estivi 2026",
  "channel": "WHATSAPP",
  "status": "DRAFT",
  "createdAt": "2026-04-09T10:00:00+02:00"
}

Step 2 — Configura template e lista destinatari

Associa il template WhatsApp approvato, la lista contatti e i parametri del template.

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-wa-2026-saldi-001 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "promo_saldi_estivi_2026",
    "contactListIds": ["list-clienti-attivi-2026"],
    "sender": "ShopItalia",
    "templateParams": {
      "header": {
        "type": "image",
        "url": "https://cdn.shopitalia.it/promo/saldi-estate-2026.jpg"
      },
      "body": [
        {"key": "1", "value": "{{nome}}"},
        {"key": "2", "value": "50%"},
        {"key": "3", "value": "30 giugno 2026"}
      ]
    },
    "scheduledDate": "2026-06-01T08:00:00.000+0200"
  }'

Response — Campagna configurata

{
  "id": "camp-wa-2026-saldi-001",
  "status": "CONFIGURED",
  "templateId": "promo_saldi_estivi_2026",
  "contactListIds": ["list-clienti-attivi-2026"],
  "scheduledDate": "2026-06-01T08:00:00.000+0200"
}

:::tip Placeholder nei parametri template Il valore {{nome}} viene sostituito automaticamente con il campo firstName del contatto in lista. Assicurati che i contatti abbiano il campo valorizzato. :::

Dietro le quinte — Invio WhatsApp bulk e rate limiting

Template validation: Il gateway verifica che il template sia in stato APPROVED su Meta Business. Template in stato PENDING o REJECTED bloccano la campagna.
Parameter mapping: I parametri body[].value vengono mappati ai placeholder {{1}}, {{2}}, ecc. definiti nel template. Il numero di parametri deve corrispondere esattamente.
Rate limiting: WhatsApp applica limiti di throughput basati sul tier del numero Business (1K, 10K, 100K msg/giorno). Il gateway gestisce automaticamente il throttling per rispettare i limiti.
Conversation window: L'invio di un template apre una finestra di conversazione di 24 ore. I messaggi di risposta dell'utente entro questa finestra non hanno costi aggiuntivi.
Quality rating: Meta monitora il quality rating del template. Tassi di blocco elevati possono portare alla sospensione del template. Monitora le metriche post-campagna.

Step 3 — Stima il costo e conferma

Calcola i destinatari raggiungibili e il costo stimato.

# Calcola il goal
curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-wa-2026-saldi-001/calculateGoal \
  -H "X-Api-Key: YOUR_API_KEY"

# Ottieni la stima dei costi
curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-wa-2026-saldi-001/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Stima costo

{
  "campaignId": "camp-wa-2026-saldi-001",
  "totalContacts": 15000,
  "reachableContacts": 14200,
  "estimatedCost": 994.00,
  "currency": "EUR",
  "costPerMessage": 0.07
}

# Conferma e schedula la campagna
curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-wa-2026-saldi-001/confirm \
  -H "X-Api-Key: YOUR_API_KEY"

Risultato atteso

Step	Azione	Risultato
1	`POST /campaigns`	Campagna creata in stato `DRAFT`
2	`PUT /campaigns/{id}`	Stato `CONFIGURED` con template e lista
3	`POST /calculateGoal`	14.200 destinatari raggiungibili su 15.000
4	`GET /price`	Costo stimato 994,00 EUR
5	`PUT /confirm`	Campagna confermata, invio schedulato

Esempio completo end-to-end

# 1. Crea campagna WhatsApp
CAMP_ID=$(curl -s -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "Saldi Estivi 2026",
    "channel": "WHATSAPP",
    "description": "Promozione saldi con coupon personalizzato"
  }' | jq -r '.id')

echo "Campaign ID: $CAMP_ID"

# 2. Configura template e lista
curl -s -X PUT "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "promo_saldi_estivi_2026",
    "contactListIds": ["list-clienti-attivi-2026"],
    "sender": "ShopItalia",
    "templateParams": {
      "body": [
        {"key": "1", "value": "{{nome}}"},
        {"key": "2", "value": "50%"},
        {"key": "3", "value": "30 giugno 2026"}
      ]
    }
  }'

# 3. Calcola goal e verifica prezzo
curl -s -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}/calculateGoal" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -s -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}/price" \
  -H "X-Api-Key: YOUR_API_KEY" | jq .

# 4. Conferma
curl -s -X PUT "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}/confirm" \
  -H "X-Api-Key: YOUR_API_KEY"

Varianti

Campagna con bottone coupon dinamico

Template con bottone contenente codice coupon univoco per destinatario:

curl -X PUT "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "coupon_personalizzato_2026",
    "contactListIds": ["list-clienti-vip"],
    "templateParams": {
      "body": [{"key": "1", "value": "{{nome}}"}],
      "buttons": [{"index": 0, "type": "copy_code", "value": "{{coupon_code}}"}]
    }
  }'

Errori comuni

400 Bad Request — Template non approvato da Meta

{
  "status": "fail",
  "data": {
    "templateId": "Template not approved by Meta or not found for channel WHATSAPP"
  }
}

Soluzione: Verifica lo stato del template su Meta Business Manager. Solo template in stato APPROVED possono essere usati. Consulta UC-013.

400 Bad Request — Parametri template non corrispondenti

{
  "status": "fail",
  "data": {
    "templateParams": "Parameter count mismatch: expected 3, got 2"
  }
}

Soluzione: Il numero di parametri nel campo body deve corrispondere esattamente ai placeholder {{1}}, {{2}}, ecc. definiti nel template approvato.

401 Unauthorized — API Key mancante o non valida

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing API key"
  }
}

Soluzione: Verifica che l'header X-Api-Key sia presente e che la chiave sia attiva nel pannello della piattaforma.

Prossimi passi

UC-021 — Campagna Bulk RCS Rich Card: Campagna visuale tramite RCS
UC-024 — Template con Link Tracciati: Misura il CTR dei bottoni nel template
UC-025 — Gestire Numeri WhatsApp Business: Verifica e gestisci i numeri mittenti
UC-013 — WhatsApp Template Workflow: Crea e gestisci template WhatsApp

Riferimenti

API Reference — Campaigns: Documentazione completa endpoint campagne
Guida WhatsApp: Specifiche del canale WhatsApp e template
Guida Autenticazione: Dettagli su API Key e Basic Auth

Scenari reali​

Ciclo di vita della campagna WhatsApp​

Prerequisiti​

Step 1 — Crea la campagna in bozza​

Response — Campagna creata​

Step 2 — Configura template e lista destinatari​

Response — Campagna configurata​

Step 3 — Stima il costo e conferma​

Response — Stima costo​

Risultato atteso​

Esempio completo end-to-end​

Varianti​

Campagna con bottone coupon dinamico​

Errori comuni​

400 Bad Request — Template non approvato da Meta​

400 Bad Request — Parametri template non corrispondenti​

401 Unauthorized — API Key mancante o non valida​

Prossimi passi​

Riferimenti​