Skip to main content

UC-012 — RCS Template Lifecycle

FieldValue
IDUC-012
GoalManage the full lifecycle of RCS templates: creation, sending, update, deletion
ChannelRCS
Complexity⭐⭐⭐ Advanced
Estimated time20 minutes
APIs involvedPOST /api/message-server/rcs/templates, GET /rcs/templates, PUT /rcs/templates/{id}, DELETE /rcs/templates/{id}, POST /api/message-server/rcs/send

Real-world scenarios​

  • TechStore — Marketing team builds reusable templates: The marketing manager creates a rich card with an image and buttons for the monthly promotions, and reuses it every month with different placeholders.
  • FashionOutlet — Seasonal templates: Templates for summer sales, Black Friday and Christmas are created in advance, used during the season, then updated or deleted.
  • ElettroShop — Product catalog: A carousel of featured products is updated every week with new images, descriptions and prices.

Prerequisites​

Before you begin, make sure you have:

Test without costs

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

Template lifecycle​

Step-by-step guide​

Step 1 — Create a TEXT template​

The simplest type: a text message with interactive suggestions.

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"
      }
    }
  }'

Response: 201 Created with the saved template (id, name, description, type, enabled, body, createdAt, updatedAt). Keep the id: it is the templateId you pass when sending.

Step 1b — Create a CARD template​

A rich card with an image, title, description and buttons:

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 — Create a CAROUSEL template​

A carousel of cards that scroll horizontally:

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 — List the templates​

Retrieve the templates, with optional filters:

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"

The response wraps the templates in a data array.

ParameterDescription
searchFull-text search on name and description
idFilter by template ID
nameFilter by template name
descriptionFilter by description
typeTEXT, CARD, CAROUSEL
enabled0 = disabled only, 1 = enabled only
sortBySort field (name, type, creationDate)
sortOrderasc or desc
limitItems per page (default 10)
pagePage number (0-based)

Step 3 — Send a message using the template​

Use the templateId obtained from the creation or from the list:

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"
    },
    "campaignId": "benvenuto-aprile-2026",
    "enableNotification": true
  }'

Response:

{
  "messageId": "b7e4f201-9a3c-4d58-a612-fedcba987654",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": true
    },
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1
    }
  }
}

The API answers 202 Accepted. The sms result is there because the template has a fallbackSms: the SMS is prepared with the message and sent only if RCS fails.

Automatic fallback

If the recipient does not support RCS, the message is sent via SMS with the text defined in the template's fallbackSms, with the same placeholders. The send request has nothing to add: a maxSmsParts field, if present, is ignored, and the SMS is split into as many parts as its text needs. You can also configure a fallbackWhatsApp to try WhatsApp before SMS; in that case fallbackSms becomes mandatory, and the WhatsApp fallback applies only if your account supports mixed-channel sending.

Step 4 — Update a template​

Change an existing template with PUT. Only the fields you send are updated; if you send body, send type as well:

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"
      }
    }
  }'

Response: 200 OK with the updated template.

Step 5 — Delete a template​

When a template is no longer needed:

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

Response: 204 No Content

Permanent deletion

Deleting a template is permanent. Messages already sent with that template are not affected, but you can no longer use it for new sends.

Template types compared​

TypeContentWhen to use it
TEXTText + suggestions (buttons)Notifications, confirmations, simple messages with actions
CARDImage/video + title + description + buttonsSingle promotions, offers with an eye-catching visual
CAROUSEL2-10 scrollable cardsProduct catalogs, comparisons, option menus

Available suggestions​

TypeDescription
replyQuick reply with predefined text
urlOpens a link in the browser
dialStarts a phone call
locationCoordinatesShows a position on a map
locationQuerySearches for an address on a map
calendarCreates a calendar event
Behind the scenes

RCS templates are managed internally by the Qlara platform, with no external approval (unlike WhatsApp templates, which require Meta's approval):

  1. Creation -- The template is saved and linked to your account. It is immediately available for sending.
  2. Rendering -- At send time, the placeholders ({name}, {codice}, etc.) are replaced with the values given in placeholders.
  3. Fallback -- If the recipient does not support RCS, the system tries fallbackWhatsApp (if configured) and then fallbackSms. The chain is: RCS -> WhatsApp -> SMS.
  4. Update -- PUT changes only the fields you send. Messages already sent are not modified.
  5. Metrics -- Use the campaignId to group the sends, then export the reports with UC-011: Export Delivery Reports.

Expected result​

AspectDetail
Action completedRCS template created, used for sending, updated or deleted
Channel usedRCS (with SMS fallback)
Delivery confirmationVia webhook (statusCode: 3) within 5-60 sec

Common errors​

ProblemProbable causeSolution
HTTP 401Missing or invalid API KeyCheck X-Api-Key header
accepted: falseInvalid number, or no operator found for it (see reasons)Verify E.164 format
HTTP 400 — Invalid template typeUnsupported type or malformed body structureVerify type is TEXT, CARD, or CAROUSEL with the matching body schema; when updating body, send type too
HTTP 404 — Template not foundWrong template ID or template was deletedList templates with GET /rcs/templates to verify the ID
Fallback SMS sent instead of RCSRecipient device does not support RCSExpected behavior; verify the fallbackSms content is appropriate
No SMS fallbackThe template has no fallbackSms, or the SMS was rejected (sms.accepted: false in the send response)Add fallbackSms to the template; check sms.reasons (e.g. SMS sender not allowed)

Next steps​