UC-021 — Campagna Bulk RCS Rich Card

Campo	Valore
ID	UC-021
Obiettivo	Creare e inviare una campagna bulk RCS con Rich Card visuale
Canale	RCS
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

• RetailModa — Promo visuale Android: RetailModa lancia la collezione estiva con una Rich Card contenente immagine del prodotto, prezzo e bottone "Acquista ora" verso 8.000 clienti Android.
• ElettronicaPlus — Lancio prodotto carousel: Presentazione di 3 nuovi smartphone con carousel di Rich Card, ciascuna con foto, specifiche e link alla scheda prodotto.
• FreshMarket — Offerta stagionale: Promozione "Frutta di stagione -40%" con immagine accattivante e bottone di risposta rapida per ordinare direttamente dalla conversazione RCS.

Ciclo di vita della campagna RCS

Il diagramma illustra il ciclo completo: dalla bozza alla configurazione con template RCS, stima costo, conferma e invio delle Rich Card ai dispositivi Android compatibili.

Prerequisiti

• API Key attiva con permessi campagne e canale RCS
• Template RCS Rich Card approvato dall'operatore (vedi UC-012)
• Lista contatti creata e popolata (vedi UC-007)
• Destinatari su dispositivi Android con supporto RCS

Step 1 — Crea la campagna in bozza

Crea una nuova campagna specificando il canale RCS.

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": "Collezione Estate 2026",
    "channel": "RCS",
    "description": "Lancio collezione estiva con Rich Card prodotto"
  }'

Response — Campagna creata

{
  "id": "camp-rcs-2026-estate-001",
  "name": "Collezione Estate 2026",
  "channel": "RCS",
  "status": "DRAFT",
  "createdAt": "2026-04-09T09:00:00+02:00"
}

Step 2 — Configura template e lista destinatari

Associa il template RCS Rich Card approvato e la lista contatti alla campagna.

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "scheduledDate": "2026-04-15T09:00:00.000+0200"
  }'

Response — Campagna configurata

{
  "id": "camp-rcs-2026-estate-001",
  "status": "CONFIGURED",
  "templateId": "rcs-tpl-richcard-estate-2026",
  "contactListIds": ["list-clienti-android-nord"],
  "scheduledDate": "2026-04-15T09:00:00.000+0200"
}

Dietro le quinte — Come funziona la Rich Card RCS

1. Template resolution: Il gateway recupera il template RCS approvato contenente layout della card (immagine, titolo, descrizione, bottoni).
2. Compatibilita dispositivo: Prima dell'invio, il sistema verifica che il destinatario abbia un dispositivo Android con RCS attivo. I dispositivi non compatibili vengono esclusi (o gestiti tramite fallback se configurato).
3. Media hosting: L'immagine della Rich Card viene servita tramite CDN del gateway. L'URL deve essere HTTPS e l'immagine non deve superare i 2 MB.
4. Rendering: Il messaggio viene renderizzato nativamente nell'app Messaggi del destinatario con layout card completo (immagine, testo, bottoni di azione).
5. Suggested actions: I bottoni possono essere di tipo URL (apri link), dialer (chiama numero) o reply (risposta rapida testuale).

Step 3 — Stima il costo e conferma

Calcola il costo stimato della campagna e procedi con la conferma.

# Calcola il goal (numero destinatari raggiungibili)
curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-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-rcs-2026-estate-001/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Stima costo

{
  "campaignId": "camp-rcs-2026-estate-001",
  "totalContacts": 8000,
  "reachableContacts": 6850,
  "estimatedCost": 342.50,
  "currency": "EUR",
  "costPerMessage": 0.05
}

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

:::tip Verifica i costi prima della conferma La conferma e irreversibile per le campagne schedulate. Controlla sempre la stima dei costi e il numero di destinatari raggiungibili prima di confermare. :::

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	Conteggio destinatari raggiungibili
4	GET /price	Stima costo totale della campagna
5	PUT /confirm	Campagna confermata, invio schedulato

Esempio completo end-to-end

# 1. Crea campagna RCS
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": "Collezione Estate 2026",
    "channel": "RCS",
    "description": "Rich Card lancio estivo"
  }' | 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": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "scheduledDate": "2026-04-15T09:00:00.000+0200"
  }'

# 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 la campagna
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 RCS con fallback SMS

Configura un fallback SMS per i destinatari senza supporto RCS:

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "fallbackChannel": "SMS",
    "fallbackBody": "Scopri la nuova collezione estiva RetailModa! -30% su tutto: https://retailmoda.it/estate2026"
  }'

Errori comuni

400 Bad Request — Template non approvato

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

Soluzione: Verifica che il template RCS sia stato approvato dall'operatore. Usa UC-012 per controllare lo stato di approvazione.

400 Bad Request — Lista contatti vuota

{
  "status": "fail",
  "data": {
    "contactListIds": "No reachable contacts found in the specified lists"
  }
}

Soluzione: Verifica che la lista contenga contatti validi con numeri in formato internazionale. I contatti senza dispositivo RCS compatibile vengono esclusi automaticamente.

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-022 — Campagna Bulk WhatsApp Template: Invia campagne bulk tramite WhatsApp con template approvati
• UC-006 — Campagna SMS Bulk: Campagna bulk classica via SMS
• UC-012 — RCS Template Workflow: Crea e gestisci template RCS
• UC-005 — Fallback Multi-Canale: Configura strategie di fallback tra canali

Riferimenti

• API Reference — Campaigns: Documentazione completa endpoint campagne
• Guida RCS: Specifiche del canale RCS e formati Rich Card
• Guida Autenticazione: Dettagli su API Key e Basic Auth