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 — Team marketing crea template riutilizzabili: Il responsabile marketing crea una rich card con immagine e pulsanti per le promozioni mensili, riutilizzandola ogni mese con placeholders diversi.
FashionOutlet — Template stagionali: Template per saldi estivi, Black Friday, Natale: vengono creati in anticipo, utilizzati durante la stagione, poi aggiornati o eliminati.
ElettroShop — Catalogo prodotti: Un carousel con i prodotti in evidenza viene aggiornato settimanalmente con nuove immagini, descrizioni e prezzi.

Prerequisites

Before you begin, make sure you have:

Active API Key → How to get one
Sufficient credit → Check in the Qlara Dashboard
RCS agentId configured

:::tip Test without costs Add "simulation": true in the request body to validate the flow without actually sending messages and without consuming credit. :::

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://lora-api.agiletelecom.com/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",
          "postbackData": "SHOW_OFFERS_NEW_CUSTOMER"
        },
        {
          "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"
      }
    }
  }'

Step 1b — Creare un template CARD

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

curl -X POST "https://lora-api.agiletelecom.com/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 scorrevoli orizzontalmente:

curl -X POST "https://lora-api.agiletelecom.com/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 tutti i template con filtri opzionali:

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

Parametro	Descrizione
`search`	Ricerca per nome/descrizione
`type`	`TEXT`, `CARD`, `CAROUSEL`
`enabled`	`0` = solo disabilitati, `1` = solo abilitati
`sortBy`	Campo ordinamento (name, type, creationDate)
`sortOrder`	`asc` o `desc`
`limit`	Elementi per pagina
`page`	Numero pagina (0-based)

Step 3 — Inviare un messaggio usando il template

Usa il templateId ottenuto dalla creazione o dalla lista:

curl -X POST "https://lora-api.agiletelecom.com/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"
    },
    "campaignId": "benvenuto-aprile-2026",
    "enableNotification": true
  }'

Risposta:

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

:::tip Fallback automatico Se il destinatario non supporta RCS, il messaggio viene inviato automaticamente via SMS usando il testo definito in fallbackSms. Puoi anche configurare un fallbackWhatsApp per tentare WhatsApp prima dell'SMS. :::

Step 4 — Aggiornare un template

Modifica un template esistente con PUT:

curl -X PUT "https://lora-api.agiletelecom.com/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"
      }
    }
  }'

Step 5 — Eliminare un template

Quando un template non serve più':

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

Risposta: 200 OK o 204 No Content

:::warning Eliminazione definitiva La cancellazione di un template e' definitiva. I messaggi già' inviati con quel template non vengono influenzati, ma non sara' 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 visual accattivante
CAROUSEL	2-10 card scorrevoli	Cataloghi prodotti, comparazioni, 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 su mappa
`locationQuery`	Cerca un indirizzo su mappa
`calendar`	Crea un evento nel calendario

Dietro le quinte

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

Creazione -- Il template viene salvato e associato al tuo account. E' immediatamente disponibile per l'invio.
Rendering -- Al momento dell'invio, i placeholders ({name}, {codice}, ecc.) vengono sostituiti con i valori specificati in placeholders.
Fallback -- Se il destinatario non supporta RCS, il sistema prova fallbackWhatsApp (se configurato) e poi fallbackSms. La catena e': RCS -> WhatsApp -> SMS.
Aggiornamento -- L'update con PUT sovrascrive completamente il template. I messaggi già' inviati non vengono modificati.
Metriche -- Usa il campaignId per raggruppare gli invii e poi esportare i report con UC-011: Export Delivery Reports.

Expected result

Aspect	Detail
Action completed	RCS template created, used for sending, updated or deleted
Channel used	RCS (with SMS fallback)
Delivery confirmation	Via webhook (statusCode: 3) within 5-60 sec

Common errors

Problem	Probable cause	Solution
HTTP `401`	Missing or invalid API Key	Check `X-Api-Key` header
`accepted: false`	Insufficient credit or invalid number	Check credit; verify E.164 format
HTTP `400` — Invalid template type	Unsupported type or malformed body structure	Verify `type` is `TEXT`, `CARD`, or `CAROUSEL` with correct body schema
HTTP `404` — Template not found	Wrong template ID or template was deleted	List templates with `GET /rcs/templates` to verify the ID
Fallback SMS sent instead of RCS	Recipient device does not support RCS	Expected behavior; verify the `fallbackSms` content is appropriate

Prossimi passi

Guida RCS Templates -- Riferimento completo sui template RCS
Guida RCS API -- Invio messaggi RCS con body inline
UC-013: WhatsApp Template Workflow -- Confronta con il flusso template WhatsApp (con approvazione Meta)
UC-010: Scheduled Messages -- Programma l'invio di template RCS
UC-011: Export Delivery Reports -- Esporta i risultati delle campagne

Scenari reali​

Prerequisites​

Ciclo di vita del template​

Guida passo-passo​

Step 1 — Creare un template TEXT​

Step 1b — Creare un template CARD​

Step 1c — Creare un template CAROUSEL​

Step 2 — Elencare i template​

Step 3 — Inviare un messaggio usando il template​

Step 4 — Aggiornare un template​

Step 5 — Eliminare un template​

Tipi di template a confronto​

Suggerimenti disponibili​

Expected result​

Common errors​

Prossimi passi​