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}, POST /campaigns/{id}/calculateGoal, 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.

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

Response — Campaign created

{
  "id": "camp-rcs-2026-estate-001",
  "name": "Collezione Estate 2026",
  "channel": "RCS",
  "status": "DRAFT",
  "createdAt": "2026-04-09T09:00:00+02:00"
}

Step 2 — Configure the template and recipient list

Associate the approved RCS Rich Card template and the contact list with the campaign.

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "scheduledDate": "2026-04-15T09:00:00.000+0200"
  }'

Response — Campaign configured

{
  "id": "camp-rcs-2026-estate-001",
  "status": "CONFIGURED",
  "templateId": "rcs-tpl-richcard-estate-2026",
  "contactListIds": ["list-clienti-android-nord"],
  "scheduledDate": "2026-04-15T09:00:00.000+0200"
}

Behind the scenes — How the RCS Rich Card works

1. Template resolution: The gateway retrieves the approved RCS template containing the card layout (image, title, description, buttons).
2. 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).
3. 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.
4. Rendering: The message is rendered natively in the recipient's Messages app with the full card layout (image, text, action buttons).
5. 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

Calculate the estimated campaign cost and proceed with confirmation.

# Calculate the goal (number of reachable recipients)
curl -X POST https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001/calculateGoal \
  -H "X-Api-Key: YOUR_API_KEY"

# Get the cost estimate
curl -X GET https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001/price \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Cost estimate

{
  "campaignId": "camp-rcs-2026-estate-001",
  "totalContacts": 8000,
  "reachableContacts": 6850,
  "estimatedCost": 342.50,
  "currency": "EUR",
  "costPerMessage": 0.05
}

# Confirm and launch the campaign
curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001/confirm \
  -H "X-Api-Key: YOUR_API_KEY"

:::tip Check costs before confirming Confirmation is irreversible for scheduled campaigns. Always check the cost estimate and the number of reachable recipients before confirming. :::

Expected result

Step	Action	Result
1	POST /campaigns	Campaign created with status DRAFT
2	PUT /campaigns/{id}	Status CONFIGURED with template and list
3	POST /calculateGoal	Reachable recipient count
4	GET /price	Total estimated campaign cost
5	PUT /confirm	Campaign confirmed, delivery scheduled

Complete end-to-end example

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

echo "Campaign ID: $CAMP_ID"

# 2. Configure template and list
curl -s -X PUT "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "scheduledDate": "2026-04-15T09:00:00.000+0200"
  }'

# 3. Calculate goal and check price
curl -s -X POST "https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/${CAMP_ID}/calculateGoal" \
  -H "X-Api-Key: YOUR_API_KEY"

curl -s -X GET "https://lora-api.agiletelecom.com/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://lora-api.agiletelecom.com/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:

curl -X PUT https://lora-api.agiletelecom.com/api/partner-gateway/v1/campaigns/camp-rcs-2026-estate-001 \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "templateId": "rcs-tpl-richcard-estate-2026",
    "contactListIds": ["list-clienti-android-nord"],
    "sender": "RetailModa",
    "fallbackChannel": "SMS",
    "fallbackBody": "Scopri la nuova collezione estiva RetailModa! -30% su tutto: https://retailmoda.it/estate2026"
  }'

Common errors

400 Bad Request — Template not approved

{
  "status": "fail",
  "data": {
    "templateId": "Template not approved or not found for channel RCS"
  }
}

Solution: Verify that the RCS template has been approved by the operator. Use UC-012 to check the approval status.

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

{
  "status": "fail",
  "data": {
    "authentication": "Invalid or missing 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