UC-021 — Bulk RCS Rich Card Campaign

Field	Value
ID	UC-021
Goal	Create and send a bulk RCS campaign with visual Rich Cards
Channel	RCS
Complexity	⭐⭐ Intermediate
Estimated time	25 minutes
APIs involved	`POST /api/partner-gateway/v1/campaigns`, `PUT /campaigns/{id}`, `GET /campaigns/{id}/price`, `PUT /campaigns/{id}/confirm`

Real-world scenarios

RetailModa — Visual Android promo: RetailModa launches its summer collection with a Rich Card containing a product image, price and "Buy now" button to 8,000 Android customers.
ElettronicaPlus — Product carousel launch: Presentation of 3 new smartphones with a Rich Card carousel, each with photo, specs and link to the product page.
FreshMarket — Seasonal offer: "Seasonal fruit -40%" promotion with an eye-catching image and a quick reply button to order directly from the RCS conversation.

RCS campaign lifecycle

The diagram illustrates the full cycle: from draft to configuration with the RCS template, cost estimation, confirmation and delivery of Rich Cards to compatible Android devices.

Prerequisites

Active API Key with campaign and RCS channel permissions
RCS Rich Card template approved by the operator (see UC-012)
Contact list created and populated (see UC-007)
Recipients on Android devices with RCS support

Step 1 — Create the campaign as a draft

Create a new campaign specifying the RCS channel (sendingMode) and recipients taken from contact lists (destinationType: 0).

curl -X POST https://api.qlara.ai/api/partner-gateway/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "Collezione Estate 2026",
    "description": "Lancio collezione estiva con Rich Card prodotto",
    "sendingMode": "RCS",
    "destinationType": 0
  }'

Response — Campaign created

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "description": "Lancio collezione estiva con Rich Card prodotto",
  "status": "DRAFT",
  "sendingMode": "RCS",
  "destinationType": 0,
  "readyToSend": false,
  "creationDate": "2026-04-09 07:00:00.000+0000"
}

Step 2 — Configure the template and recipient list

Associate the RCS agent, the Rich Card template (rcsTemplateType is the type of the template) and the contact list with the campaign, then mark it as ready with readyToSend: true.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "RCS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "readyToSend": true
  }'

Response — Campaign configured

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "RCS",
  "rcsAgentId": "retailmoda_k3v9x2pq_agent",
  "rcsTemplateId": 2216,
  "rcsTemplateType": "CARD",
  "contactListIds": [412],
  "scheduledDate": "2026-04-15 07:00:00.000+0000",
  "readyToSend": true
}

Behind the scenes — How the RCS Rich Card works

Template resolution: The gateway retrieves the approved RCS template containing the card layout (image, title, description, buttons).
Device compatibility: Before sending, the system verifies that the recipient has an Android device with active RCS. Incompatible devices are excluded (or handled via fallback if configured).
Media hosting: The Rich Card image is served through the gateway's CDN. The URL must be HTTPS and the image must not exceed 2 MB.
Rendering: The message is rendered natively in the recipient's Messages app with the full card layout (image, text, action buttons).
Suggested actions: Buttons can be of type URL (open link), dialer (call number) or reply (quick text reply).

Step 3 — Estimate the cost and confirm

Check the campaign's price and proceed with confirmation.

# Get the cost estimate
curl -X GET https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Cost estimate

{
  "id": 3821,
  "name": "Collezione Estate 2026",
  "status": "READY_TO_SEND",
  "sendingMode": "RCS",
  "rcsTemplateId": 2216,
  "contactListIds": [412],
  "totalPrice": 40000000000,
  "walletKind": "EURO",
  "numOfDistinctContact": 8000,
  "readyToSend": true
}

numOfDistinctContact is the number of distinct recipients and totalPrice the total price of the campaign, in the unit of the wallet named by walletKind: for EURO, hundred-millionths of a euro, so 40000000000 is €400.

# Confirm and launch the campaign (202 Accepted, no body)
curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821/confirm \
  -H "X-Api-Key: YOUR_API_KEY"

Check costs before confirming

Confirmation is irreversible for scheduled campaigns. Always check the cost estimate and the number of recipients (numOfDistinctContact) before confirming.

Expected result

Step	Action	Result
1	`POST /campaigns`	Campaign created with status `DRAFT`
2	`PUT /campaigns/{id}`	Status `READY_TO_SEND` with agent, template and list
3	`GET /price`	`totalPrice` and `numOfDistinctContact`
4	`PUT /confirm`	`202 Accepted`: campaign confirmed, delivery scheduled

Complete end-to-end example

# 1. Create RCS campaign
CAMP_ID=$(curl -s -X POST https://api.qlara.ai/api/partner-gateway/v1/campaigns \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "name": "Collezione Estate 2026",
    "description": "Rich Card lancio estivo",
    "sendingMode": "RCS",
    "destinationType": 0
  }' | jq -r '.id')

echo "Campaign ID: $CAMP_ID"

# 2. Configure agent, template and list
curl -s -X PUT "https://api.qlara.ai/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "RCS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "readyToSend": true
  }'

# 3. Check the price
curl -s -X GET "https://api.qlara.ai/api/partner-gateway/v1/campaigns/${CAMP_ID}/price" \
  -H "X-Api-Key: YOUR_API_KEY" | jq .

# 4. Confirm the campaign
curl -s -X PUT "https://api.qlara.ai/api/partner-gateway/v1/campaigns/${CAMP_ID}/confirm" \
  -H "X-Api-Key: YOUR_API_KEY"

Variants

RCS campaign with SMS fallback

Configure an SMS fallback for recipients without RCS support: set sendingMode to RCS_SMS and add the SMS sender and text.

curl -X PUT https://api.qlara.ai/api/partner-gateway/v1/campaigns/3821 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "sendingMode": "RCS_SMS",
    "rcsAgentId": "retailmoda_k3v9x2pq_agent",
    "rcsTemplateId": 2216,
    "rcsTemplateType": "CARD",
    "contactListIds": [412],
    "smsSender": "RetailModa",
    "smsBody": "Scopri la nuova collezione estiva RetailModa! -30% su tutto: https://retailmoda.it/estate2026",
    "scheduledDate": "2026-04-15 09:00:00.000+0200",
    "readyToSend": true
  }'

The price changes with the sending mode: call GET /price again before confirming.

Common errors

400 Bad Request — Template type mismatch

{
  "status": "fail",
  "data": {
    "rcsTemplateType": "RCS template type CARD does not match the type of template 2216 (CAROUSEL)"
  }
}

Solution: Set rcsTemplateType to the type of the template (TEXT, CARD or CAROUSEL). Check the template and its type as shown in UC-012.

400 Bad Request — Empty contact list

{
  "status": "fail",
  "data": {
    "contactListIds": "No reachable contacts found in the specified lists"
  }
}

Solution: Verify that the list contains valid contacts with phone numbers in international format. Contacts without a compatible RCS device are automatically excluded.

401 Unauthorized — Missing or invalid API Key

{
  "error": "Invalid API Key"
}

Solution: Verify that the X-Api-Key header is present and that the key is active in the platform dashboard.

Next steps

UC-022 — Bulk WhatsApp Template Campaign: Send bulk campaigns via WhatsApp with approved templates
UC-006 — Bulk SMS Campaign: Classic bulk campaign via SMS
UC-012 — RCS Template Workflow: Create and manage RCS templates
UC-005 — Multi-Channel Fallback: Configure fallback strategies between channels

References

API Reference — Campaigns: Full campaign endpoint documentation
RCS Guide: RCS channel specifications and Rich Card formats
Authentication Guide: Details on API Key and Basic Auth

Real-world scenarios​

RCS campaign lifecycle​

Prerequisites​

Step 1 — Create the campaign as a draft​

Response — Campaign created​

Step 2 — Configure the template and recipient list​

Response — Campaign configured​

Step 3 — Estimate the cost and confirm​

Response — Cost estimate​

Expected result​

Complete end-to-end example​

Variants​

RCS campaign with SMS fallback​

Common errors​

400 Bad Request — Template type mismatch​

400 Bad Request — Empty contact list​

401 Unauthorized — Missing or invalid API Key​

Next steps​

References​