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

Response — Campagna creata

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "description": "Lancio collezione estiva con Rich Card prodotto",
  "status": "DRAFT",
  "sendingMode": "RCS",
  "destinationType": 0,
  "readyToSend": false,
  "creationDate": "2026-04-09 07:00:00.000+0000"
}

Step 2 — Configura template e lista destinatari

Associa alla campagna l'agente RCS, il template Rich Card (rcsTemplateType è il tipo del template) e la lista contatti, poi segnalala come pronta con readyToSend: true.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "RCS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "readyToSend": true
  }'

Response — Campagna configurata

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "RCS",
  "rcsAgentId": "retailmoda_k3v9x2pq_agent",
  "rcsTemplateId": 2216,
  "rcsTemplateType": "CARD",
  "contactListIds": [412],
  "scheduledDate": "2026-04-15 07:00:00.000+0000",
  "readyToSend": true
}

Dietro le quinte — Come funziona la Rich Card RCS

Template resolution: Il gateway recupera il template RCS approvato contenente layout della card (immagine, titolo, descrizione, bottoni).
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).
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.
Rendering: Il messaggio viene renderizzato nativamente nell'app Messaggi del destinatario con layout card completo (immagine, testo, bottoni di azione).
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.

# Ricalcola destinatari e costo
curl -X POST https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821/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/3821/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Stima costo

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "RCS",
  "rcsTemplateId": 2216,
  "contactListIds": [412],
  "totalPrice": 40000000000,
  "numOfDistinctContact": 8000,
  "readyToSend": true
}

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

# Conferma e avvia la campagna (202 Accepted, senza body)
curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821/confirm \
  -H "X-Api-Key: YOUR_API_KEY"

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 (numOfDistinctContact) prima di confermare.

Risultato atteso

Step	Azione	Risultato
1	`POST /campaigns`	Campagna creata in stato `DRAFT`
2	`PUT /campaigns/{id}`	Stato `READY_TO_SEND` con agente, template e lista
3	`POST /calculateGoal`	Destinatari e costo ricalcolati
4	`GET /price`	`totalPrice` e `numOfDistinctContact`
5	`PUT /confirm`	`202 Accepted`: campagna confermata, invio schedulato

Esempio completo end-to-end

# 1. Crea campagna RCS
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": "Collezione Estate 2026",
    "description": "Rich Card lancio estivo",
    "sendingMode": "RCS",
    "destinationType": 0
  }' | jq -r '.id')

echo "Campaign ID: $CAMP_ID"

# 2. Configura agente, 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": "RCS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "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 la campagna
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 RCS con fallback SMS

Configura un fallback SMS per i destinatari senza supporto RCS: imposta sendingMode a RCS_SMS e aggiungi mittente e testo dell'SMS.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "RCS_SMS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "smsSender": "RetailModa",
    "smsBody": "Scopri la nuova collezione estiva RetailModa! -30% su tutto: https://retailmoda.it/estate2026",
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "readyToSend": true
  }'

Il prezzo cambia con la modalità di invio: richiama calculateGoal e GET /price prima di confermare.

Errori comuni

400 Bad Request — Tipo di template non corrispondente

{
  "status": "fail",
  "data": {
    "rcsTemplateType": "RCS template type CARD does not match the type of template 2216 (CAROUSEL)"
  }
}

Soluzione: Imposta rcsTemplateType al tipo del template (TEXT, CARD o CAROUSEL). Verifica il template e il suo tipo come mostrato in UC-012.

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

Scenari reali​

Ciclo di vita della campagna RCS​

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 RCS con fallback SMS​

Errori comuni​

400 Bad Request — Tipo di template non corrispondente​

400 Bad Request — Lista contatti vuota​

401 Unauthorized — API Key mancante o non valida​

Prossimi passi​

Riferimenti​