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 (sendingMode) e destinatari presi dalle liste contatti (destinationType: 0).

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

Response — Campagna creata

{
  "id": 3907,
  "name": "Saldi Estivi 2026",
  "description": "Promozione saldi estivi -50% con coupon personalizzato",
  "status": "DRAFT",
  "sendingMode": "WHATSAPP",
  "destinationType": 0,
  "readyToSend": false,
  "creationDate": "2026-04-09 08:00:00.000+0000"
}

Step 2 — Configura template e lista destinatari

Associa alla campagna il numero WhatsApp Business, il template WhatsApp approvato e la lista contatti, poi segnalala come pronta con readyToSend: true.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3907 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "WHATSAPP",
    "whatsappPhoneNumberId": 5,
    "whatsappTemplateId": 188,
    "contactListIds": [415],
    "scheduledDate": "2026-06-01 08:00:00.000+0200",
    "readyToSend": true
  }'

Response — Campagna configurata

{
  "id": 3907,
  "name": "Saldi Estivi 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "WHATSAPP",
  "whatsappPhoneNumberId": 5,
  "whatsappTemplateId": 188,
  "contactListIds": [415],
  "scheduledDate": "2026-06-01 06:00:00.000+0000",
  "readyToSend": true
}

Variabili del template

La campagna non porta parametri del template: ogni variabile del template approvato (per esempio {firstName}) viene valorizzata per ciascun destinatario con il campo corrispondente del contatto in lista. Assicurati che i contatti abbiano quei campi valorizzati.

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.
Risoluzione delle variabili: Le variabili definite nel template vengono risolte per ciascun destinatario dal record del contatto, quindi la richiesta della campagna non le elenca mai.
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

Ricalcola i destinatari e il costo stimato.

# Ricalcola destinatari e costo
curl -X POST https://api.qlara.ai/api/partner-gateway/v1/campaigns/3907/calculateGoal \
  -H "X-Api-Key: YOUR_API_KEY"

# Ottieni la stima dei costi
curl -X GET https://api.qlara.ai/api/partner-gateway/v1/campaigns/3907/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Stima costo

{
  "id": 3907,
  "name": "Saldi Estivi 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "WHATSAPP",
  "whatsappTemplateId": 188,
  "contactListIds": [415],
  "totalPrice": 105000000000,
  "numOfDistinctContact": 15000,
  "readyToSend": true
}

# Conferma e schedula la campagna (202 Accepted, senza body)
curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3907/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 `READY_TO_SEND` con numero, template e lista
3	`POST /calculateGoal`	Destinatari e costo ricalcolati
4	`GET /price`	15.000 destinatari distinti (`numOfDistinctContact`) e `totalPrice`
5	`PUT /confirm`	`202 Accepted`: campagna confermata, invio schedulato

Esempio completo end-to-end

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

echo "Campaign ID: $CAMP_ID"

# 2. Configura numero, template e lista
curl -s -X PUT "https://api.qlara.ai/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "WHATSAPP",
    "whatsappPhoneNumberId": 5,
    "whatsappTemplateId": 188,
    "contactListIds": [415],
    "readyToSend": true
  }'

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

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

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

Varianti

Campagna con codice coupon personalizzato

La campagna non può passare un valore diverso a ciascun destinatario: un codice coupon univoco deve arrivare dal record del contatto. Salva il codice di ogni cliente sul contatto (vedi UC-007), usa un template approvato che lo mostri nel testo tramite una variabile e collega la campagna a quel template:

curl -X PUT "https://api.qlara.ai/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "WHATSAPP",
    "whatsappPhoneNumberId": 5,
    "whatsappTemplateId": 192,
    "contactListIds": [416],
    "readyToSend": true
  }'

Errori comuni

400 Bad Request — Template non approvato da Meta

{
  "status": "fail",
  "data": {
    "whatsappTemplateId": "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 — Campi WhatsApp mancanti

{
  "status": "fail",
  "data": {
    "whatsappPhoneNumberId": "Required when sendingMode includes WHATSAPP"
  }
}

Soluzione: Ogni modalità di invio che include WhatsApp richiede sia whatsappPhoneNumberId sia whatsappTemplateId. Impostali con PUT /campaigns/{id} prima di confermare.

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 codice coupon personalizzato​

Errori comuni​

400 Bad Request — Template non approvato da Meta​

400 Bad Request — Campi WhatsApp mancanti​

401 Unauthorized — API Key mancante o non valida​

Prossimi passi​

Riferimenti​