ITA – RCS API / Creazione Template

Template (text) #

Struttura #

Messaggio testuale con possibili azioni e SMS di fallback.

{
  "type": "TEXT",
  "body": {
    "text": "Testo del messaggio",   // obbligatorio
    "suggestions": [ ... ],          // opzionale
    "fallbackSms": { ... }           // opzionale
  }
}

Obbligatori #

• text non vuoto ne nullo.

Esempio di RCS testuale con SMS di fallback #

{
  "name": "RCS - Benvenuto (Text)",
  "description": "Messaggio di benvenuto con fallback SMS",
  "type": "TEXT",
  "body": {
    "text": "Ciao {name}, benvenuto nel nostro servizio!",
    "suggestions": [
      { "type": "url",  "text": "Sito",  "url": { "url": "https://agiletelecom.com" } },
      { "type": "dial", "text": "Chiama","dial": { "phoneNumber": "+39037224525" } }
    ],
    "fallbackSms": { "sender": "AGILE", "text": "Ciao {name}, benvenuto!" }
  }
}

Template CARD (rich card singola) #

Riquadro con media (immagine/video), titolo, descrizione e, facoltativamente, suggestions.

Struttura #

{
  "type": "CARD",
  "body": {
    "cardOrientation": "VERTICAL | HORIZONTAL | UNSPECIFIED", // obbligatorio
    "thumbnailAlignment": "LEFT | RIGHT | UNSPECIFIED",       // opzionale
    "card": {                                                 // obbligatorio
      "title": "Titolo",            // opzionale
      "description": "Descrizione", // opzionale
      "media": {                    // opzionale
        "height": "SHORT | MEDIUM | TALL | UNSPECIFIED", // obbligatorio se presente il media
        "fileUrl": "https://..."   // Url del media file da inserire nella card
      },
      "suggestions": [ ... ]        // opzionale
    },
    "suggestions": [ ... ],         // opzionale (azioni globali)
    "fallbackSms": { ... }          // opzionale
  }
}

Esempio #

{
  "name": "RCS - Promo Autunno (Card)",
  "description": "Card verticale con immagine e azioni",
  "type": "CARD",
  "body": {
    "cardOrientation": "VERTICAL",
    "card": {
      "title": "Offerta d'autunno",
      "description": "Sconto 20% sui prodotti selezionati",
      "media": {
        "height": "TALL",
        "fileUrl": "https://cdn.example.com/img/offerta.jpg"
      },
      "suggestions": [
        { "type": "url", "text": "Scopri", "url": { "url": "https://shop.example.com/offerta" } }
      ]
    },
    "suggestions": [
      { "type": "dial", "text": "Chiama", "dial": { "phoneNumber": "+39037224525" } }
    ],
    "fallbackSms": { "sender": "AGILE", "text": "Promo -20% su shop.example.com" }
  }
}

Template CAROUSEL (più card) #

Lista scorrevole di 2–10 card, ognuna con media e azioni proprie.

Struttura #

{
  "type": "CAROUSEL",
  "body": {
    "cardWidth": "SMALL | MEDIUM | UNSPECIFIED", // obbligatorio
    "cards": [                                    // obbligatorio
      {
        "title": "Titolo",            // opzionale
        "description": "Descrizione", // opzionale
        "media": {                    // opzionale
          "height": "SHORT | MEDIUM | TALL | UNSPECIFIED", // obbligatorio
          "fileUrl": "https://..."  
        },
        "suggestions": [ ... ]        // opzionale (per la card visibili sotto la card)
      }
      // ... altre card ...
    ],
    "suggestions": [ ... ],           // opzionale (azioni globali visibili sotto il carousel)
    "fallbackSms": { ... }            // opzionale
  }
}

Esempio #

{
  "name": "RCS - Menu Ristorante (Carousel)",
  "description": "Carosello con piatti e azioni",
  "type": "CAROUSEL",
  "body": {
    "cardWidth": "MEDIUM",
    "cards": [
      {
        "title": "Antipasti",
        "description": "Un abbraccio di sapori.",
        "media": { "height": "SHORT", "fileUrl": "https://cdn.example.com/a.jpg" },
        "suggestions": [
          { "type": "dial", "text": "Chiama subito", "dial": { "phoneNumber": "+39037224525" } }
        ]
      },
      {
        "title": "Primi",
        "description": "Pasta fresca a km0.",
        "media": { "height": "SHORT", "fileUrl": "https://cdn.example.com/p.jpg" },
        "suggestions": [
          { "type": "url", "text": "Visita il sito", "url": { "url": "https://agiletelecom.com/" } }
        ]
      }
    ],
    "suggestions": [
      {
        "type": "calendar",
        "text": "Partecipa alla presentazione",
        "calendar": {
          "title": "Save the date",
          "description": "Presentazione del nuovo menu",
          "startTime": "2026-06-02T11:00:00Z",
          "endTime":   "2026-06-02T13:00:00Z"
        }
      }
    ],
    "fallbackSms": { "sender": "AGILE", "text": "Scopri il menu: agiletelecom.com" }
  }
}

Suggestions: tipi e campi #

Formati data: usa ISO-8601 (es. 2026-06-02T11:00:00Z o +01:00). #

Media nelle card #

Di seguito si riporta l’enumerato che definisce la dimensione del media.
Si ricorda che l’indirizzo definito in fileUrl deve essere pubblicamente accessibile e mantenuto online fino al termine dell’invio del messaggio; la mancanza del media in fase di invio causa un errore che può compromettere il corretto invio del RCS

• height obbligatorio: "SHORT" | "MEDIUM" | "TALL" | "UNSPECIFIED".
• Specificare sempre fileUrl che definisce l’indirizzo del media.

Enumerazioni #

Di seguito si riportano gli enumerato utilizzabili in fase di definizione dei template RCS.

• Type: TEXT, CARD, CAROUSEL.
• cardOrientation: VERTICAL, HORIZONTAL, UNSPECIFIED
• thumbnailAlignment: LEFT, RIGHT, UNSPECIFIED.
• height: SHORT, MEDIUM, TALL, UNSPECIFIED
• cardWidth: SMALL, MEDIUM, UNSPECIFIED

Placeholder nel testo #

Usa segnaposto nel text (es. {name}); la sostituzione avviene in fase di invio.
All’interno del testo è possibile definire quanti template si deisderano attraverso l’uso delle parentesi graffe; in fase di invio saranno sostituiti dai valori definiti nella chiamata

NB: Se in fase di invio non sarà fornito un valore per un placeholter questo non avrà alcuna sostituzione e la dicitura con le graffe (es. {name}) resterà all’interno del messaggio RCS

Checklist errori comuni #

• TEXT: manca body.text.
• CARD: mancano body.card o body.card.media.height.
• CAROUSEL: manca body.cardWidth o cards è vuoto.
• Media: manca fileUrl o non è raggiungibile dall’esterno.
• Suggestions: type incoerente con l’oggetto compilato.