UC-006 — Campagna SMS Bulk a Migliaia di Destinatari

Campo	Valore
ID	UC-006
Obiettivo	Creare e inviare una campagna SMS bulk con stima dei costi e monitoraggio
Canale	SMS
Complessità	⭐⭐ Intermedio
Tempo stimato	20 minuti
API coinvolte	`POST /api/partner-gateway/v1/campaigns`, `PUT /campaigns/{id}`, `POST /campaigns/{id}/calculateGoal`, `GET /campaigns/{id}/price`, `PUT /campaigns/{id}/confirm`, `GET /campaigns/stats`

Scenari reali

ShopItalia — Black Friday: Promozione flash a 10.000 clienti con codice sconto personalizzato e scadenza a 48 ore. Invio immediato il venerdi mattina alle 08:00.
Studio Dentistico Bianchi — Reminder settimanali: Ogni lunedi il sistema invia un promemoria degli appuntamenti della settimana a tutti i pazienti prenotati.
AcquaLuce Energia — Scadenza bolletta: Avviso di pagamento in scadenza a tutti i clienti con fattura non saldata, con link al portale di pagamento.

Ciclo di vita della campagna

Il diagramma illustra le transizioni di stato: dalla creazione (Draft) alla configurazione, stima costo, conferma e infine invio.

Step 1 — Crea la campagna (Draft)

Crea una nuova campagna in stato bozza specificando nome, canale e descrizione.

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": "Black Friday 2026",
    "channel": "SMS",
    "description": "Promozione Black Friday - sconto 30% su tutto il catalogo"
  }'

Response — Campagna creata

{
  "id": 1542,
  "name": "Black Friday 2026",
  "channel": "SMS",
  "description": "Promozione Black Friday - sconto 30% su tutto il catalogo",
  "status": "DRAFT",
  "createdAt": "2026-04-09T09:00:00Z"
}

:::tip Salva l'ID campagna Il campo id e l'identificativo che userai in tutti gli step successivi. Salvalo per tracciare la campagna. :::

Step 2 — Configura messaggio e destinatari (Configured)

Associa la lista contatti, il mittente e il testo del messaggio alla campagna.

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sender": "ShopItalia",
    "text": "Black Friday! Solo per te: -30% su tutto con il codice BF2026. Valido fino al 30/11. Scopri di più: https://shop.example.it/bf",
    "contactListId": 87,
    "unicode": false
  }'

Response — Campagna configurata

{
  "id": 1542,
  "name": "Black Friday 2026",
  "channel": "SMS",
  "status": "CONFIGURED",
  "sender": "ShopItalia",
  "text": "Black Friday! Solo per te: -30% su tutto con il codice BF2026. Valido fino al 30/11. Scopri di più: https://shop.example.it/bf",
  "contactListId": 87,
  "unicode": false,
  "updatedAt": "2026-04-09T09:02:00Z"
}

:::info Lista contatti La contactListId deve riferirsi a una lista già creata. Vedi UC-007 — Gestione Contatti e Liste per creare e popolare le liste. :::

Step 3 — Calcola il costo (CostCalculated)

Prima di confermare, verifica quanti destinatari validi ci sono e quante parti SMS saranno necessarie.

curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542/calculateGoal \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Costo calcolato

{
  "id": 1542,
  "status": "COST_CALCULATED",
  "totalRecipients": 10247,
  "validRecipients": 9831,
  "invalidRecipients": 416,
  "estimatedParts": 9831,
  "calculatedAt": "2026-04-09T09:03:00Z"
}

Dietro le quinte — Validazione destinatari

Durante il calcolo, il sistema esegue queste operazioni:

Deduplicazione: Rimuove numeri duplicati presenti nella lista.
Validazione formato: Scarta numeri non in formato internazionale o con sintassi errata.
Stima parti: Analizza il testo per determinare il numero di SMS per messaggio (1 parte = 160 char GSM-7, 70 char UCS-2).
Blacklist: Esclude numeri presenti nelle liste di opt-out o blacklist di sistema.

I 416 destinatari invalidi in questo esempio includono numeri duplicati, malformati o in blacklist.

Step 4 — Verifica il prezzo

Controlla il costo totale in crediti prima di procedere con la conferma.

curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Prezzo stimato

{
  "id": 1542,
  "totalRecipients": 9831,
  "pricePerMessage": 0.035,
  "totalPrice": 344.09,
  "currency": "EUR",
  "availableCredit": 1500.00,
  "sufficient": true
}

:::warning Credito insufficiente Se sufficient e false, la conferma fallira. Ricarica il credito prima di procedere. :::

Step 5 — Conferma e avvia l'invio

Conferma la campagna per avviare l'invio immediato.

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542/confirm \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendImmediately": true
  }'

Response — Campagna confermata

{
  "id": 1542,
  "status": "CONFIRMED",
  "sendImmediately": true,
  "confirmedAt": "2026-04-09T09:05:00Z"
}

Variante — Invio schedulato

Per programmare l'invio in una data futura, usa scheduledDate al posto di sendImmediately:

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/1542/confirm \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "scheduledDate": "2026-11-29T08:00:00.000+0000"
  }'

Step 6 — Monitora l'avanzamento

Controlla le statistiche di delivery in tempo reale durante e dopo l'invio.

curl -X GET "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/stats?campaignId=1542" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Campagna completata

{
  "campaignId": 1542,
  "name": "Black Friday 2026",
  "status": "COMPLETED",
  "stats": {
    "total": 9831,
    "sent": 9831,
    "delivered": 9542,
    "undelivered": 289,
    "pending": 0,
    "deliveryRate": 97.06
  },
  "cost": {
    "totalCredits": 344.09,
    "currency": "EUR"
  },
  "completedAt": "2026-04-09T09:47:00Z"
}

Risultato finale: 9.542 messaggi consegnati su 9.831 destinatari validi (97,06%), costo totale 344,09 EUR.

Errori comuni

400 Bad Request — Lista contatti non configurata

{
  "status": "fail",
  "data": {
    "contactListId": "Contact list is required before calculating cost"
  }
}

Soluzione: Assicurati di aver completato lo Step 2 (configurazione) prima di richiedere il calcolo del costo.

402 — Credito insufficiente

{
  "status": "fail",
  "data": {
    "credit": "Insufficient credit. Required: 344.09, available: 120.00"
  }
}

Soluzione: Ricarica il credito dal pannello della piattaforma prima di confermare la campagna.

Risultato atteso

Step	Azione	Risultato
1	`POST /campaigns`	Campagna in stato `DRAFT`, `id` restituito
2	`PUT /campaigns/{id}`	Stato `CONFIGURED`, testo e lista associati
3	`POST /campaigns/{id}/calculateGoal`	Stato `COST_CALCULATED`, destinatari validati
4	`GET /campaigns/{id}/price`	Costo totale e verifica credito sufficiente
5	`PUT /campaigns/{id}/confirm`	Stato `CONFIRMED` → `SENDING`
6	`GET /campaigns/stats`	Statistiche delivery in tempo reale

Prossimi passi

UC-007 — Gestione Contatti e Liste: Crea e popola le liste contatti per le tue campagne
UC-008 — Tracking Consegna con Webhooks: Ricevi notifiche di delivery in tempo reale
Guida Campagne: Approfondisci scheduling, filtri e gestione avanzata

Scenari reali​

Ciclo di vita della campagna​

Step 1 — Crea la campagna (Draft)​

Response — Campagna creata​

Step 2 — Configura messaggio e destinatari (Configured)​

Response — Campagna configurata​

Step 3 — Calcola il costo (CostCalculated)​

Response — Costo calcolato​

Step 4 — Verifica il prezzo​

Response — Prezzo stimato​

Step 5 — Conferma e avvia l'invio​

Response — Campagna confermata​

Variante — Invio schedulato​

Step 6 — Monitora l'avanzamento​

Response — Campagna completata​

Errori comuni​

400 Bad Request — Lista contatti non configurata​

402 — Credito insufficiente​

Risultato atteso​

Prossimi passi​