UC-012 — Ciclo di Vita dei Template RCS

Campo	Valore
ID	UC-012
Obiettivo	Gestire il ciclo completo dei template RCS: creazione, invio, aggiornamento, eliminazione
Canale	RCS
Complessità	⭐⭐⭐ Avanzato
Tempo stimato	20 minuti
API coinvolte	POST /api/message-server/rcs/templates, GET /rcs/templates, PUT /rcs/templates/{id}, DELETE /rcs/templates/{id}, POST /api/message-server/rcs/send

Scenari reali

• TechStore — Il team marketing crea template riutilizzabili: Il responsabile marketing crea una rich card con immagine e pulsanti per le promozioni mensili e la riutilizza ogni mese con placeholder diversi.
• FashionOutlet — Template stagionali: I template per saldi estivi, Black Friday e Natale vengono creati in anticipo, usati durante la stagione, poi aggiornati o eliminati.
• ElettroShop — Catalogo prodotti: Un carousel con i prodotti in evidenza viene aggiornato ogni settimana con nuove immagini, descrizioni e prezzi.

Prerequisiti

Prima di iniziare, assicurati di avere:

• API Key attiva → Come ottenerla
• Credito sufficiente → Verificalo nella Dashboard Qlara
• agentId RCS configurato

Test senza costi

Aggiungi "simulation": true nel body della richiesta di invio per validare il flusso senza inviare davvero i messaggi e senza consumare credito.

Ciclo di vita del template

Guida passo-passo

Step 1 — Creare un template TEXT

Il tipo più semplice: un messaggio di testo con suggerimenti interattivi.

curl -X POST "https://api.qlara.ai/api/message-server/rcs/templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "benvenuto_cliente",
    "description": "Template di benvenuto per nuovi clienti",
    "type": "TEXT",
    "body": {
      "text": "Ciao {name}! Benvenuto in TechStore. Siamo felici di averti con noi. Scopri le offerte riservate ai nuovi clienti!",
      "suggestions": [
        {
          "type": "reply",
          "text": "Mostra offerte",
          "reply": {}
        },
        {
          "type": "url",
          "text": "Visita il sito",
          "url": { "url": "https://techstore.it/benvenuto" }
        },
        {
          "type": "dial",
          "text": "Chiamaci",
          "dial": { "phoneNumber": "+390212345678" }
        }
      ],
      "fallbackSms": {
        "sender": "TechStore",
        "text": "Ciao {name}! Benvenuto in TechStore. Scopri le offerte: https://techstore.it/benvenuto"
      }
    }
  }'

Risposta: 201 Created con il template salvato (id, name, description, type, enabled, body, createdAt, updatedAt). Conserva l'id: è il templateId da passare in fase di invio.

Step 1b — Creare un template CARD

Una rich card con immagine, titolo, descrizione e pulsanti:

curl -X POST "https://api.qlara.ai/api/message-server/rcs/templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "promo_estate_2026",
    "description": "Promozione saldi estivi con immagine",
    "type": "CARD",
    "body": {
      "cardOrientation": "VERTICAL",
      "thumbnailAlignment": "LEFT",
      "card": {
        "title": "Saldi Estivi TechStore",
        "description": "Fino al 40% di sconto su tutta la collezione estate. Offerta valida fino al 31 luglio 2026.",
        "media": {
          "height": "TALL",
          "fileUrl": "https://cdn.techstore.it/img/saldi-estate-2026.jpg"
        },
        "suggestions": [
          {
            "type": "url",
            "text": "Scopri i saldi",
            "url": { "url": "https://techstore.it/saldi-estate" }
          },
          {
            "type": "calendar",
            "text": "Ricordami la scadenza",
            "calendar": {
              "title": "Fine saldi estivi TechStore",
              "description": "Ultimo giorno per i saldi estivi!",
              "startTime": "2026-07-31T09:00:00Z",
              "endTime": "2026-07-31T23:59:00Z"
            }
          }
        ]
      },
      "fallbackSms": {
        "sender": "TechStore",
        "text": "Saldi estivi TechStore! Fino al 40% di sconto. Scopri: https://techstore.it/saldi-estate"
      }
    }
  }'

Step 1c — Creare un template CAROUSEL

Un carousel con più card che scorrono in orizzontale:

curl -X POST "https://api.qlara.ai/api/message-server/rcs/templates" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "catalogo_prodotti_top",
    "description": "Carousel prodotti in evidenza",
    "type": "CAROUSEL",
    "body": {
      "cardWidth": "MEDIUM",
      "cards": [
        {
          "title": "Cuffie Wireless Pro",
          "description": "79.99 EUR - Noise cancelling attivo",
          "media": {
            "height": "MEDIUM",
            "fileUrl": "https://cdn.techstore.it/img/cuffie-pro.jpg"
          },
          "suggestions": [
            {
              "type": "url",
              "text": "Dettagli",
              "url": { "url": "https://techstore.it/p/cuffie-pro" }
            }
          ]
        },
        {
          "title": "Smartwatch FitPlus",
          "description": "149.99 EUR - GPS integrato",
          "media": {
            "height": "MEDIUM",
            "fileUrl": "https://cdn.techstore.it/img/smartwatch-fitplus.jpg"
          },
          "suggestions": [
            {
              "type": "url",
              "text": "Dettagli",
              "url": { "url": "https://techstore.it/p/smartwatch" }
            }
          ]
        },
        {
          "title": "Speaker Bluetooth Mini",
          "description": "39.99 EUR - Waterproof IP67",
          "media": {
            "height": "MEDIUM",
            "fileUrl": "https://cdn.techstore.it/img/speaker-mini.jpg"
          },
          "suggestions": [
            {
              "type": "url",
              "text": "Dettagli",
              "url": { "url": "https://techstore.it/p/speaker-mini" }
            }
          ]
        }
      ],
      "fallbackSms": {
        "sender": "TechStore",
        "text": "Scopri i prodotti in evidenza su TechStore: https://techstore.it/top"
      }
    }
  }'

Step 2 — Elencare i template

Recupera i template, con filtri opzionali:

curl -X GET "https://api.qlara.ai/api/message-server/rcs/templates?type=CARD&sortBy=creationDate&sortOrder=desc&limit=10&page=0" \
  -H "X-Api-Key: YOUR_API_KEY"

La risposta racchiude i template in un array data.

Parametro	Descrizione
search	Ricerca full-text su nome e descrizione
id	Filtra per ID del template
name	Filtra per nome del template
description	Filtra per descrizione
type	TEXT, CARD, CAROUSEL
enabled	0 = solo disabilitati, 1 = solo abilitati
sortBy	Campo di ordinamento (name, type, creationDate)
sortOrder	asc o desc
limit	Elementi per pagina (default 10)
page	Numero di pagina (da 0)

Step 3 — Inviare un messaggio con il template

Usa il templateId ottenuto dalla creazione o dalla lista:

curl -X POST "https://api.qlara.ai/api/message-server/rcs/send" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "destination": "+393471234567",
    "agentId": 1,
    "templateId": 55,
    "placeholders": {
      "name": "Laura"
    },
    "maxSmsParts": 2,
    "campaignId": "benvenuto-aprile-2026",
    "enableNotification": true
  }'

Risposta:

{
  "messageId": "b7e4f201-9a3c-4d58-a612-fedcba987654",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": true,
      "reasons": []
    },
    "sms": null
  }
}

Fallback automatico

Se il destinatario non supporta RCS, il messaggio viene inviato via SMS con il testo definito in fallbackSms. Il fallback SMS scatta solo se la richiesta di invio imposta maxSmsParts: se il testo di fallback richiede più parti, l'SMS viene saltato, non troncato. Puoi anche configurare un fallbackWhatsApp per tentare WhatsApp prima dell'SMS; in quel caso fallbackSms diventa obbligatorio.

Step 4 — Aggiornare un template

Modifica un template esistente con PUT. Vengono aggiornati solo i campi che invii; se invii body, invia anche type:

curl -X PUT "https://api.qlara.ai/api/message-server/rcs/templates/55" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "benvenuto_cliente_v2",
    "description": "Template benvenuto aggiornato con nuove offerte",
    "type": "TEXT",
    "body": {
      "text": "Ciao {name}! Benvenuto in TechStore. Usa il codice WELCOME10 per il 10% di sconto sul primo acquisto!",
      "suggestions": [
        {
          "type": "url",
          "text": "Usa lo sconto",
          "url": { "url": "https://techstore.it/promo/WELCOME10" }
        }
      ],
      "fallbackSms": {
        "sender": "TechStore",
        "text": "Ciao {name}! Benvenuto in TechStore. Codice sconto WELCOME10 su techstore.it"
      }
    }
  }'

Risposta: 200 OK con il template aggiornato.

Step 5 — Eliminare un template

Quando un template non serve più:

curl -X DELETE "https://api.qlara.ai/api/message-server/rcs/templates/55" \
  -H "X-Api-Key: YOUR_API_KEY"

Risposta: 204 No Content

Eliminazione definitiva

L'eliminazione di un template è definitiva. I messaggi già inviati con quel template non vengono toccati, ma non sarà più possibile usarlo per nuovi invii.

Tipi di template a confronto

Tipo	Contenuto	Quando usarlo
TEXT	Testo + suggerimenti (pulsanti)	Notifiche, conferme, messaggi semplici con azioni
CARD	Immagine/video + titolo + descrizione + pulsanti	Promozioni singole, offerte con un visual accattivante
CAROUSEL	2-10 card scorrevoli	Cataloghi prodotti, confronti, menu di opzioni

Suggerimenti disponibili

Tipo	Descrizione
reply	Risposta rapida con testo predefinito
url	Apre un link nel browser
dial	Avvia una chiamata
locationCoordinates	Mostra una posizione sulla mappa
locationQuery	Cerca un indirizzo sulla mappa
calendar	Crea un evento nel calendario

Dietro le quinte

I template RCS sono gestiti internamente dalla piattaforma Qlara, senza approvazione esterna (a differenza dei template WhatsApp, che richiedono l'approvazione di Meta):

1. Creazione -- Il template viene salvato e associato al tuo account. È subito disponibile per l'invio.
2. Rendering -- Al momento dell'invio, i placeholder ({name}, {codice}, ecc.) vengono sostituiti con i valori indicati in placeholders.
3. Fallback -- Se il destinatario non supporta RCS, il sistema prova fallbackWhatsApp (se configurato) e poi fallbackSms. La catena è: RCS -> WhatsApp -> SMS.
4. Aggiornamento -- PUT modifica solo i campi che invii. I messaggi già inviati non vengono modificati.
5. Metriche -- Usa il campaignId per raggruppare gli invii e poi esportare i report con UC-011: Export Report di Consegna.

Risultato atteso

Aspetto	Dettaglio
Azione completata	Template RCS creato, usato per l'invio, aggiornato o eliminato
Canale usato	RCS (con fallback SMS)
Conferma di consegna	Via webhook (statusCode: 3) entro 5-60 secondi

Errori comuni

Problema	Causa probabile	Soluzione
HTTP 401	API Key mancante o non valida	Controlla l'header X-Api-Key
accepted: false	Credito insufficiente o numero non valido	Verifica il credito e il formato E.164
HTTP 400 — Tipo di template non valido	Tipo non supportato o struttura del body malformata	Verifica che type sia TEXT, CARD o CAROUSEL con lo schema di body corrispondente; quando aggiorni body, invia anche type
HTTP 404 — Template non trovato	ID template errato o template eliminato	Elenca i template con GET /rcs/templates per verificare l'ID
SMS di fallback inviato al posto dell'RCS	Il dispositivo del destinatario non supporta RCS	Comportamento atteso; verifica che il contenuto di fallbackSms sia adeguato
Nessun fallback SMS	maxSmsParts assente nella richiesta di invio, oppure il testo di fallback richiede più parti	Imposta maxSmsParts abbastanza alto per il testo di fallbackSms

Prossimi passi

• Guida Template RCS -- Riferimento completo sui template RCS
• Guida RCS API -- Invio di messaggi RCS con body inline
• UC-013: Template WhatsApp -- Confronta con il flusso dei template WhatsApp (con approvazione Meta)
• UC-010: Invio Programmato -- Programma l'invio di template RCS
• UC-011: Export Report di Consegna -- Esporta i risultati delle campagne