View Categories

ENG – RCS API / Template Creation

4 min read

This guide describes how to build the JSON body of the POST /rcs/template/create calls used to create new RCS templates. The documentation is intended both for developers and product roles.

Basic payload structure #

{
  "name": "Nome leggibile",
  "description": "Breve descrizione del template",
  "type": "TEXT | CARD | CAROUSEL",
  "body": { ... contenuto del template ... }
}

Common fields (in body) #

fallbackSms (optional) #

SMS sent if RCS is not available on the device.

"fallbackSms": {
  "sender": "SMS-SENDER",   // obbligatorio se presente fallbackSms
  "text":   "Testo SMS"     // obbligatorio se presente fallbackSms
}

If fallbackSms is defined, both sender and text are mandatory.

suggestions (optional) #

User-triggered buttons/actions whose structure must comply with Table 5: “Suggestions: types and fields”. Each entry has:

  • type (e.g. "url", "dial", "reply", "coordinates", "location", "calendar")
  • text (button label, optional).
"suggestions": [
  { "type": "url",  "text": "Visita sito", "url": { "url": "https://example.com" } },
  { "type": "dial", "text": "Chiama",      "dial": { "phoneNumber": "+39037224525" } }
]

Template (text) #

Structure #

Text message with optional actions and SMS fallback.

{
  "type": "TEXT",
  "body": {
    "text": "Testo del messaggio",   // obbligatorio
    "suggestions": [ ... ],          // opzionale
    "fallbackSms": { ... }           // opzionale
  }
}
Required #
  • text must not be empty or null.
Example: Text RCS with SMS 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 (single rich card) #

Card with media (image/video), title, description and optional suggestions.

Structure #
{
  "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://..."   
      },
      "suggestions": [ ... ]        
    },
    "suggestions": [ ... ],         
    "fallbackSms": { ... }          
  }
}
Example #
{
  "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 (multiple cards) #

Scrollable list of 2–10 cards, each with its own media and actions.

Structure #
{
  "type": "CAROUSEL",
  "body": {
    "cardWidth": "SMALL | MEDIUM | UNSPECIFIED", // obbligatorio
    "cards": [                                    
      {
        "title": "Titolo",
        "description": "Descrizione",
        "media": {                    
          "height": "SHORT | MEDIUM | TALL | UNSPECIFIED",
          "fileUrl": "https://..."  
        },
        "suggestions": [ ... ]        
      }
    ],
    "suggestions": [ ... ],           
    "fallbackSms": { ... }            
  }
}
Example #
{
  "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: types and fields #

type Oggetto Obbligatori Esempio
"reply" reply — { "type":"reply", "text":"Ok", "reply":{} }
"url" url url.url { "type":"url", "text":"Apri", "url":{"url":"https://..."} }
"dial" dial dial.phoneNumber { "type":"dial", "text":"Chiama", "dial":{"phoneNumber":"+390372..."} }
"coordinates" locationCoordinates latitude, longitude { "type":"coordinates", "text":"Posizione", "locationCoordinates":{"label":"Store","latitude":45.1,"longitude":10.0} }
"location" locationQuery locationQuery.query { "type":"location", "text":"Cerca", "locationQuery":{"query":"farmacie"} }
"calendar" calendar startTime, endTime { "type":"calendar", "text":"Aggiungi evento", "calendar":{"title":"Demo","startTime":"2026-06-02T11:00:00Z","endTime":"2026-06-02T12:00:00Z"} }
Date formats: use ISO-8601 (e.g. 2026-06-02T11:00:00Z or +01:00). #

Media in cards #

Below is the enumeration defining media height. Ensure that fileUrl is publicly accessible and remains online until the message has been fully processed; missing media may cause RCS delivery errors.

  • height is required: "SHORT" | "MEDIUM" | "TALL" | "UNSPECIFIED".
  • Always specify fileUrl, defining the media location.

Enumerations #

Below are the enumerations available when defining RCS templates.

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

Placeholders in text #

Use placeholders inside text (e.g. {name}); they are replaced at send time.
You may include as many placeholders as needed using curly braces. They will be replaced with the values provided in the request.

Note: If a value is not provided at send time, the placeholder will not be replaced and will remain visible inside the RCS message (e.g. {name}).

Common error checklist #

  • TEXT: missing body.text.
  • CARD: missing body.card or body.card.media.height.
  • CAROUSEL: missing body.cardWidth or cards is empty.
  • Media: missing fileUrl or not reachable.
  • Suggestions: type inconsistent with the provided object.
What are your Feelings

Via Baldassarre Peruzzi 26, 41012 – Carpi (MO)

VAT ID: IT02804070361

Agile Telecom is part of Growens

Products

SMS

2Way

Smart content verification

HLR Lookup

Testing Tool

Industries

Communications

Information Technology

Financial services

Marketing

Developers

Documentation

How we work

Our experience

Our people

Get in touch

Contact Us

Privacy Policy

Compliance

GDPR Infrastructure

Terms of Service

Private Area

AgCom Regulation