Passa al contenuto principale

UC-006 — Campagna SMS Bulk a Migliaia di Destinatari

CampoValore
IDUC-006
ObiettivoCreare e inviare una campagna SMS bulk con stima dei costi e monitoraggio
CanaleSMS
Complessità⭐⭐ Intermedio
Tempo stimato20 minuti
API coinvoltePOST /api/partner-gateway/v1/campaigns, PUT /campaigns/{id}, POST /campaigns/{id}/calculateGoal, GET /campaigns/{id}/price, PUT /campaigns/{id}/confirm, GET /campaigns/{id}

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, descrizione, canale (sendingMode) e come vengono scelti i destinatari (destinationType: 0, dalle liste contatti).

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

Response — Campagna creata​

{
  "id": 1542,
  "name": "Black Friday 2026",
  "description": "Promozione Black Friday - sconto 30% su tutto il catalogo",
  "status": "DRAFT",
  "sendingMode": "SMS",
  "destinationType": 0,
  "readyToSend": false,
  "creationDate": "2026-04-09 09:00:00.000+0000"
}
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. readyToSend: true segna la configurazione come definitiva, così la campagna può essere confermata.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/1542 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "SMS",
    "smsSender": "ShopItalia",
    "smsBody": "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",
    "contactListIds": [87],
    "readyToSend": true
  }'

Response — Campagna configurata​

{
  "id": 1542,
  "name": "Black Friday 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "SMS",
  "smsSender": "ShopItalia",
  "smsBody": "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",
  "destinationType": 0,
  "contactListIds": [87],
  "readyToSend": true,
  "lastUpdateDate": "2026-04-09 09:02:00.000+0000"
}
Lista contatti

Gli ID in contactListIds devono riferirsi a liste già create. Vedi UC-007 — Gestione Contatti e Liste per creare e popolare le liste.

Step 3 — Calcola il costo (CostCalculated)​

Prima di confermare, ricalcola destinatari e costo a partire dalla configurazione attuale della campagna. La risposta è la campagna aggiornata; il prezzo si legge nello Step 4.

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

Response — Costo calcolato​

{
  "id": 1542,
  "name": "Black Friday 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "SMS",
  "smsSender": "ShopItalia",
  "destinationType": 0,
  "contactListIds": [87],
  "readyToSend": true
}
Dietro le quinte — Destinatari e prezzo

Il calcolo parte dalla configurazione attuale della campagna:

  1. Deduplicazione: Le liste selezionate vengono unite e ogni numero viene contato una sola volta (numOfDistinctContact nello Step 4).
  2. Tariffa: Il prezzo dipende dal sendingMode, dal numero di destinatari e dalla tariffa per messaggio del tuo account.
  3. Parti SMS: Un testo entro 160 caratteri GSM-7 (70 UCS-2) è un solo SMS; uno più lungo viene inviato in più parti concatenate, fino a 1530 caratteri.
  4. Valori non aggiornati: Richiama calculateGoal dopo aver cambiato liste, testo o sendingMode, altrimenti il prezzo può risultare zero o non aggiornato.

Step 4 — Verifica il prezzo​

Controlla il prezzo totale prima di procedere con la conferma.

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

Response — Prezzo stimato​

{
  "id": 1542,
  "name": "Black Friday 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "SMS",
  "contactListIds": [87],
  "totalPrice": 34408500000,
  "numOfDistinctContact": 9831,
  "readyToSend": true
}

numOfDistinctContact è il numero di destinatari distinti (9.831) e totalPrice il prezzo totale della campagna.

Credito insufficiente

Se il tuo credito non copre totalPrice, la conferma fallirà con 400. Ricarica il credito prima di procedere.

Step 5 — Conferma e avvia l'invio​

Conferma la campagna per avviare l'invio immediato. La richiesta non ha body.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/1542/confirm \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Campagna confermata​

202 Accepted, senza body: la campagna è in coda e, non avendo una scheduledDate, l'invio parte subito.

Variante — Invio schedulato​

Per programmare l'invio in una data futura, imposta scheduledDate (formato yyyy-MM-dd HH:mm:ss.SSSZ) sulla campagna prima di confermarla:

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/1542 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "SMS",
    "scheduledDate": "2026-11-29 08:00:00.000+0000",
    "readyToSend": true
  }'

Poi confermala con PUT /campaigns/1542/confirm come sopra: la campagna viene inviata alla data programmata.

Step 6 — Monitora l'avanzamento​

Controlla i contatori di delivery della campagna durante e dopo l'invio.

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/campaigns/1542" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Campagna completata​

{
  "id": 1542,
  "name": "Black Friday 2026",
  "status": "ENDED",
  "sendingMode": "SMS",
  "startDate": "2026-04-09 09:05:02.000+0000",
  "endDate": "2026-04-09 09:47:00.000+0000",
  "totalDestinations": 9831,
  "totalPrice": 34408500000,
  "totalSent": 9831,
  "totalSuccess": 9542,
  "totalFailed": 289,
  "smsSent": 9831,
  "smsPending": 0,
  "smsSuccess": 9542,
  "smsFailed": 289
}

Risultato finale: 9.542 messaggi consegnati (totalSuccess) su 9.831 inviati (totalSent), un tasso di consegna del 97,06%. Per l'esito di ogni singolo messaggio, esporta i delivery report della campagna (vedi UC-029).

Errori comuni​

400 Bad Request — Lista contatti non configurata​

{
  "status": "fail",
  "data": {
    "contactListIds": "At least one contact list is required to confirm the campaign"
  }
}

Soluzione: Assicurati di aver completato lo Step 2 (configurazione) prima di calcolare il costo e confermare.

400 Bad Request — Credito insufficiente​

{
  "status": "fail",
  "data": {
    "credit": "Insufficient credit to cover the campaign totalPrice"
  }
}

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

Risultato atteso​

StepAzioneRisultato
1POST /campaignsCampagna in stato DRAFT, id restituito
2PUT /campaigns/{id}Stato READY_TO_SEND, testo e lista associati
3POST /campaigns/{id}/calculateGoalDestinatari e costo ricalcolati
4GET /campaigns/{id}/pricetotalPrice e numOfDistinctContact
5PUT /campaigns/{id}/confirm202 Accepted, l'invio parte
6GET /campaigns/{id}Stato ENDED, contatori di delivery

Prossimi passi​