UC-002 — Send RCS Rich Card

Field	Value
ID	UC-002
Goal	Send an RCS rich card with media, text, and interactive actions
Channel	RCS
Complexity	Basic
Estimated time	15 minutes
APIs involved	POST /api/message-server/rcs/send, GET /api/partner-gateway/v1/messages/status/{customerMessageId}

Real-world scenarios

• Retail — Product promotion: ElettroShop sends a rich card with a product photo, discounted price, and a "Buy now" button linking directly to the offer page.
• Restaurant — Visual menu: Trattoria Da Mario sends the daily special with a dish photo, description, and a button to book a table.
• Real estate — Property listing: Immobiliare Rossi sends a card with an apartment photo, details, and buttons to call the agent or open the map.

Prerequisites

Before you begin, make sure you have:

• Active API Key → How to get one
• Sufficient credit → Check in the Qlara Dashboard
• RCS agentId configured in the Qlara platform

Test without costs

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

Message flow

Unlike an SMS, the RCS rich card allows you to send multimedia content with interactive buttons directly in the phone's native conversation, without the need for external apps.

Step 1 — Prepare the media URL

The rich card image must be accessible via a public HTTPS URL. Supported formats: JPEG, PNG. Recommended size: at least 1440px wide for optimal rendering.

Media requirements

The URL must be publicly reachable (no localhost, no VPN). Use a CDN or object storage (S3, GCS) to ensure availability and performance.

Step 2 — Send the Rich Card

Call the RCS endpoint with type: "CARD" and the card content in the body field.

curl -X POST https://api.qlara.ai/api/message-server/rcs/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393401234567",
    "agentId": 10,
    "body": {
      "type": "CARD",
      "body": {
        "title": "Samsung Galaxy S26 Ultra",
        "description": "Offerta esclusiva ElettroShop! Solo per oggi: Galaxy S26 Ultra a 899 EUR invece di 1.199 EUR. Spedizione gratuita e reso entro 30 giorni.",
        "mediaUrl": "https://cdn.elettroshop.it/products/galaxy-s26-ultra.jpg",
        "suggestions": [
          {
            "type": "URL",
            "text": "Acquista ora",
            "value": "https://elettroshop.it/galaxy-s26-ultra?promo=RCS2026"
          },
          {
            "type": "REPLY",
            "text": "Maggiori info",
            "value": "INFO_GALAXY_S26"
          },
          {
            "type": "DIAL",
            "text": "Chiama negozio",
            "value": "+390212345678"
          }
        ]
      }
    },
    "enableNotification": true
  }'

Response — Message accepted

{
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": true,
      "reasons": []
    },
    "sms": null
  }
}

Behind the scenes — Rich Card structure

The RCS rich card is composed of:

• title (required): Main title of the card, displayed in bold.
• description (optional): Descriptive text below the title.
• mediaUrl (optional): URL of the image or video displayed at the top of the card.
• suggestions (optional): List of interactive buttons. Supported types:
  • URL — Opens a link in the browser
  • REPLY — Sends a predefined reply (the value is the payload received via the INBOUND webhook)
  • DIAL — Starts a phone call to the specified number

The gateway verifies the reachability of the mediaUrl at the time of sending. If the image is not accessible, the message is still sent but without media.

Available suggestion types

Type	Behavior	Example value
URL	Opens the browser	https://example.it/page
REPLY	Sends a reply to the bot	INFO_PRODUCT_42
DIAL	Starts a call	+390212345678

Step 3 — Verify delivery

curl -X GET "https://api.qlara.ai/api/partner-gateway/v1/messages/status/e76614d1-4ac1-4d94-89f0-d07f1b5a190c?channel=RCS" \
  -H "X-Api-Key: YOUR_API_KEY"

Response — Delivered

{
  "customerMessageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "channel": "RCS",
  "destination": "+393401234567",
  "deliveryStatus": "DELIVERED",
  "deliveryStatusDescription": "delivered",
  "sendDate": "2026-04-09T11:30:00+02:00",
  "deliveryDate": "2026-04-09T11:30:02+02:00",
  "readDate": null
}

Read receipt

Unlike SMS, RCS tells you when the user views the message, but only through the READ webhook event. On the status API the message stays DELIVERED and readDate is always null for RCS.

Webhook events

Behind the scenes — RCS delivery and read webhooks

For RCS you receive three types of callbacks:

DELIVERY — The message has been delivered:

{
  "eventType": "DELIVERY",
  "channel": "RCS",
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "destination": "+393401234567",
  "statusCode": 3,
  "description": "delivered",
  "eventDate": "2026-04-09T11:30:02+02:00",
  "price": 0.04
}

READ — The user has viewed the message:

{
  "eventType": "READ",
  "channel": "RCS",
  "messageId": "e76614d1-4ac1-4d94-89f0-d07f1b5a190c",
  "destination": "+393401234567",
  "eventDate": "2026-04-09T11:31:15+02:00"
}

INBOUND — The user pressed a REPLY button:

{
  "eventType": "INBOUND",
  "channel": "RCS",
  "messageId": "inbound-msg-001",
  "source": "+393401234567",
  "destination": "ag-2_ci5xnlho_agent",
  "receivedDate": "2026-04-09T11:32:00+02:00",
  "messageType": "TEXT",
  "text": "INFO_GALAXY_S26"
}

In the INBOUND event, source is the user's number and, on RCS, destination is your agent id.

Configure your endpoint in the Webhook guide.

SMS Fallback configuration

If the recipient does not support RCS, you can enable automatic SMS fallback by setting maxSmsParts:

curl -X POST https://api.qlara.ai/api/message-server/rcs/send \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -d '{
    "destination": "+393401234567",
    "agentId": 10,
    "body": {
      "type": "CARD",
      "body": {
        "title": "Offerta ElettroShop",
        "description": "Galaxy S26 Ultra a 899 EUR. Spedizione gratuita!",
        "mediaUrl": "https://cdn.elettroshop.it/products/galaxy-s26-ultra.jpg",
        "suggestions": [
          {
            "type": "URL",
            "text": "Acquista ora",
            "value": "https://elettroshop.it/galaxy-s26-ultra"
          }
        ]
      }
    },
    "maxSmsParts": 3,
    "enableNotification": true
  }'

Response — SMS fallback activated

{
  "messageId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "simulation": false,
  "results": {
    "rcs": {
      "accepted": false,
      "reasons": ["RCS not available"]
    },
    "sms": {
      "accepted": true,
      "unicode": false,
      "parts": 1,
      "reasons": []
    }
  }
}

Fallback and content

When SMS fallback is triggered, the rich card content (images, buttons) is lost. The gateway sends only text. For a better experience, consider also configuring a custom fallback text.

Common errors

Invalid agentId

{
  "status": "fail",
  "data": {
    "agentId": "Agent not found or not associated with your account"
  }
}

Solution: Verify the agentId in the RCS section of the platform dashboard. Each account has an associated RCS agent.

Unreachable media URL

The message is accepted (accepted: true) but the card arrives without an image. Verify that the URL is:

• HTTPS (not HTTP)
• Publicly accessible
• A valid image format (JPEG, PNG)

Expected result

Step	Action	Result
1	Prepare media URL	Image accessible via HTTPS
2	POST /rcs/send (type: CARD)	messageId returned, accepted: true
3	GET /messages/status/{id}?channel=RCS	deliveryStatus: "DELIVERED" (the read arrives as a READ webhook event; readDate stays null)

Next steps

• UC-001 — Send Single SMS: Basic scenario with SMS channel
• UC-003 — Send WhatsApp Template: WhatsApp messages with approved templates
• UC-004 — Check Delivery Status: Batch polling and webhook comparison
• RCS Guide: Complete RCS channel documentation
• RCS Templates Guide: Create and manage RCS templates