Gestione Campagne

Le campagne ti permettono di inviare messaggi a più contatti contemporaneamente, con pianificazione, stima dei costi e analitiche dettagliate.

Ciclo di Vita della Campagna

Ogni campagna segue questo flusso di lavoro:

Draft → Configurato → Costo Calcolato → Confermato/Pianificato → Invio → Completato

1. Draft — Campagna creata, setup iniziale
2. Configurato — Tutte le impostazioni finalizzate (contatti, canale, messaggio)
3. Costo Calcolato — Sistema stima il costo totale
4. Confermato/Pianificato — Approvato e pronto per l'invio (immediato o pianificato)
5. Invio — I messaggi sono in fase di consegna
6. Completato — Tutti i messaggi inviati

Creazione di una Campagna

Endpoint: POST /campaigns

{
  "name": "Spring Promotion 2025",
  "channel": "sms",
  "message": "Spring sale is here! 30% off everything. Shop now: https://example.com/spring",
  "contactList": "list_12345",
  "sendImmediately": false,
  "scheduledTime": "2025-04-15T09:00:00Z"
}

Campi della Richiesta

Campo	Tipo	Richiesto	Descrizione
name	string	Sì	Nome della campagna
channel	string	Sì	sms, rcs, o whatsapp
message	string	Sì	Contenuto del messaggio (per SMS) o templateId (per RCS/WhatsApp)
contactList	string	Sì	ID della lista contatti a cui inviare
sendImmediately	boolean	No	Invia ora (default: false)
scheduledTime	ISO 8601	No	Invia in questo momento (se non immediato)
fallback	boolean	No	Abilita fallback canale (default: false)

Aggiornamento di una Campagna

Endpoint: PUT /campaigns/{id}

Aggiorna la campagna prima di inviarla (solo stato Draft o Configurato):

{
  "name": "Spring Promotion 2025 - Updated",
  "message": "New offer text",
  "scheduledTime": "2025-04-16T10:00:00Z"
}

Non puoi modificare campagne che sono in stato Confermato, Invio o Completato.

Calcolo del Costo

Prima di confermare, stima il costo totale.

Endpoint: POST /campaigns/{id}/calculateGoal

{
  "goalContactCount": 5000
}

Risposta:

{
  "totalContacts": 5000,
  "estimatedCost": 250.00,
  "costPerMessage": 0.05,
  "currency": "EUR",
  "estimatedDuration": "15 minutes"
}

Fattori di Costo

• SMS: Più economico (~0.03-0.05 EUR per messaggio)
• RCS: Medio (~0.05-0.10 EUR per messaggio)
• WhatsApp: Più costoso (~0.10-0.20 EUR per messaggio)

I prezzi variano per paese e volume.

Ottenimento del Prezzo della Campagna

Endpoint: GET /campaigns/{id}/price

Ottieni il prezzo finale prima di confermare:

{
  "campaignId": "camp_12345",
  "totalContacts": 5000,
  "estimatedCost": 250.00,
  "breakdown": {
    "sms": { "count": 0, "cost": 0 },
    "rcs": { "count": 0, "cost": 0 },
    "whatsapp": { "count": 0, "cost": 0 }
  }
}

Conferma di una Campagna

Endpoint: PUT /campaigns/{id}/confirm

Conferma e passa allo stato Confermato. Dopo questo, non puoi modificare la campagna.

curl -X PUT https://lora-api.agiletelecom.com/api/campaigns/camp_12345/confirm \
  -H "X-Api-Key: your_api_key_here"

Risposta:

{
  "id": "camp_12345",
  "status": "confirmed",
  "scheduledTime": "2025-04-15T09:00:00Z",
  "message": "Campaign confirmed. Sending starts at scheduled time."
}

Una volta confermata, la campagna invierà al momento pianificato (o immediatamente se sendImmediately: true).

Annullamento di una Campagna

Endpoint: DELETE /campaigns/{id}

Annulla una campagna (solo stato Draft, Configurato, o Confermato):

curl -X DELETE https://lora-api.agiletelecom.com/api/campaigns/camp_12345 \
  -H "X-Api-Key: your_api_key_here"

Non puoi annullare campagne che sono in stato Invio o Completato.

Statistiche della Campagna

Endpoint: GET /campaigns/{id}/stats

Ottieni analitiche della campagna in tempo reale:

curl -X GET https://lora-api.agiletelecom.com/api/campaigns/camp_12345/stats \
  -H "X-Api-Key: your_api_key_here"

Risposta:

{
  "campaignId": "camp_12345",
  "name": "Spring Promotion 2025",
  "status": "sending",
  "totalMessages": 5000,
  "sent": 3200,
  "delivered": 2890,
  "failed": 310,
  "pending": 1800,
  "deliveryRate": 0.578,
  "failureRate": 0.062,
  "startTime": "2025-04-15T09:00:00Z",
  "estimatedCompletionTime": "2025-04-15T09:45:00Z"
}

Campi di Statistiche

Campo	Descrizione
sent	Messaggi inviati ai carrier (hanno lasciato i nostri server)
delivered	Consegnati con successo ai destinatari
failed	Falliti (numero non valido, rifiuto operatore, ecc.)
pending	Non ancora inviati
deliveryRate	delivered / sent
failureRate	failed / sent

Best Practice

Pianificazione

1. Testa prima — Invia una piccola campagna di test per verificare il contenuto del messaggio e i contatti
2. Rivedi i contatti — Assicurati che i numeri di telefono siano validi e che i contatti abbiano dato il consenso
3. Controlla il costo — Chiama sempre calculateGoal prima di confermare grandi campagne
4. Usa template — Per RCS e WhatsApp, usa template pre-approvati per un'elaborazione più veloce

Esecuzione

1. Pianifica fuori dalla fascia oraria di punta — Evita di inviare durante le finestre di manutenzione dell'operatore (tipicamente 2-4 AM)
2. Monitora all'inizio — Controlla le statistiche nei primi minuti per rilevare problemi
3. Imposta le aspettative — La consegna richiede tempo. Controlla di nuovo in 30-60 minuti per il completamento
4. Gestisci i fallimenti — Monitora i messaggi non riusciti e riprova con fallback SMS se necessario

Analitiche

1. Monitora il tasso di consegna — Punta al 90%+ di tasso di consegna. Investiga se inferiore.
2. Monitora i fallimenti — Un alto tasso di fallimento indica dati di contatto non validi
3. Confronta i canali — WhatsApp ha il tasso di consegna più alto, SMS è il più affidabile
4. Ottimizza il momento di invio — Sperimenta con giorni/ore diverse per massimizzare l'engagement

Limiti della Campagna

Limite	Valore
Max contatti per campagna	1,000,000
Max campagne (attive)	10
Min lunghezza messaggio	1 carattere
Max lunghezza messaggio	160 (SMS), 1000 (RCS), 1000 (WhatsApp)

Casi d'Uso Comuni

Campagna Promozionale

{
  "name": "Spring Sale",
  "channel": "sms",
  "message": "40% off everything! Code: SPRING2025",
  "contactList": "active_customers",
  "scheduledTime": "2025-04-15T10:00:00Z"
}

Campagna in Due Fasi (SMS + WhatsApp)

1. Invia SMS a tutti i contatti (veloce, alto raggiungimento)
2. Invia WhatsApp solo agli utenti coinvolti (alto engagement)

{
  "name": "Important Update - SMS Phase",
  "channel": "sms",
  "message": "Account update required. Tap here: https://example.com/update",
  "contactList": "all_users",
  "sendImmediately": true
}

Quindi più tardi:

{
  "name": "Important Update - WhatsApp Phase",
  "channel": "whatsapp",
  "message": "template_id_approved_by_meta",
  "contactList": "engaged_users",
  "scheduledTime": "2025-04-16T14:00:00Z"
}

Campagna Transazionale (Conferme di Ordine)

Usa l'endpoint di messaggio singolo invece:

curl -X POST https://lora-api.agiletelecom.com/api/message-server/sms/send \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "phoneNumber": "+393901234567",
    "message": "Order confirmed. Tracking: https://example.com/track/12345"
  }'

Le campagne sono per invii di massa. Per messaggi transazionali individuali, usa l'endpoint di invio diretto.

Passaggi Successivi

• Quick Start — Invia il tuo primo messaggio
• Webhook — Traccia la consegna della campagna in tempo reale
• Canali di Messaggistica — Scegli il miglior canale

Hai domande? Contatta support@agiletelecom.com.