RCS Rich Media Reference

This page provides the complete specification for Rich Cards, Carousels, and Suggestions used in the EnableX RCS API. Use this as a reference when constructing card, carousel, and suggestions payloads for both session messages and templates.

Supported Media Types

Rich cards and carousels support the following media file types. Media files must be hosted on a publicly accessible HTTPS URL or uploaded in advance using a file upload API.

Rich Card Specification

A rich card combines media, text, and interactive suggestions into a single visual message. Rich cards are ideal for product showcases, promotional banners, appointment confirmations, and any scenario where visual context enhances the message.

A rich card should always include either suggested replies or suggested actions alongside the media — media alone is not recommended as a standalone rich card.

Rich Card JSON Structure

The card object is used inside the message payload when type is "card":

{
  "title": "Product Name",
  "description": "Product description text",
  "url": "https://example.com/product-image.jpg",
  "thumbnail_url": "https://example.com/product-thumb.jpg",
  "suggestions": [
    {
      "type": "open_url",
      "text": "View Details",
      "url": "https://example.com/product",
      "postback": "view_product"
    }
  ]
}

Rich Card Rules

Card Height

Rich cards expand vertically to fit their content, with a minimum height of 112 DP and a maximum of 344 DP. Media within rich cards must fit one of three predefined heights:

If the media does not fit the dimensions within the card at the selected height, the platform zooms and crops the media to fit.

Card Orientation

Vertical Rich Cards

Display horizontal media at the top of the card. Recommended for most use cases.

Horizontal Rich Cards

Display vertical media on the left or right side of the card. Useful for contact cards or compact layouts.

Carousel Specification

A carousel presents multiple rich cards in a horizontally scrollable strip. Users swipe through the cards and can interact with each one individually. Carousels are ideal for product catalogs, plan comparisons, appointment time slots, or any multi-option selection.

Carousel JSON Structure

The carousel field is an array of rich card objects (same structure as a standalone card):

{
  "type": "carousel",
  "phone": "+919876543210",
  "agent": "your-agent-name",
  "carousel": [
    {
      "title": "Option A",
      "description": "Description of option A",
      "url": "https://example.com/option-a.jpg",
      "suggestions": [
        {
          "type": "reply",
          "text": "Select A",
          "postback": "selected_a"
        }
      ]
    },
    {
      "title": "Option B",
      "description": "Description of option B",
      "url": "https://example.com/option-b.jpg",
      "suggestions": [
        {
          "type": "reply",
          "text": "Select B",
          "postback": "selected_b"
        }
      ]
    }
  ],
  "fallback_text": "View options at https://example.com/options"
}

Carousel Rules

Truncation Behavior

In a carousel, the height of the first few cards determines the height of all cards. If a device cannot display all elements of a card due to display constraints, the platform truncates content in this order:

1. Reduce description to one line → 2. Reduce title to one line → 3. Remove suggestions from the end of the list → 4. Remove description entirely → 5. Remove title entirely.

Suggestions Reference

Suggestions are interactive buttons displayed within messages or rich cards. Each message or card supports up to 4 suggestions. Suggestion display text is limited to 25 characters.

Suggestions fall into two categories that cannot be mixed on a single card:

Standard Suggestion JSON

Every suggestion object shares these common fields:

{
  "type": "reply | open_url | dial | view_location | share_location | create_calendar_event",
  "text": "Button Label (max 25 chars)",
  "postback": "postback_value_for_business (max 2048 chars)"
}

Suggested Reply

Guides users through conversations by providing quick response options. When tapped, the reply text and postback data are sent to your webhook.

{
  "type": "reply",
  "text": "Yes, Confirm",
  "postback": "order_confirmed"
}

Open URL

Opens the specified URL in the user's browser. If a native app is registered as the default handler for the URL, that app opens instead.

{
  "type": "open_url",
  "text": "Track Shipment",
  "url": "https://example.com/track/SHP-789",
  "postback": "track_shipment_789"
}

Dial a Phone Number

Opens the phone dialer with the specified number pre-filled. The number must include a leading +, country code, and area code with no separators.

{
  "type": "dial",
  "text": "Call Us",
  "phone": "+911234567890",
  "postback": "called_support"
}

View Location

Opens the default map application and drops a pin at the specified coordinates. You can set a custom label for the pin.

{
  "type": "view_location",
  "text": "View Store",
  "latitude": "28.4595",
  "longitude": "77.0266",
  "label": "EnableX Office",
  "fallback": "https://maps.google.com/?q=28.4595,77.0266",
  "postback": "viewed_store_location"
}

Share Location

Prompts the user to share a location. The shared coordinates (latitude/longitude) are posted to your webhook. The user can share any location — not necessarily their current position.

{
  "type": "share_location",
  "text": "Share Address",
  "postback": "user_shared_address"
}

Create Calendar Event

Opens the user's calendar app with a pre-filled event containing the title, description, and time range you specify.

{
  "type": "create_calendar_event",
  "text": "Add to Calendar",
  "title": "Service Appointment",
  "description": "Vehicle service at AutoCare Center",
  "start_time": "2025-04-01T09:00:00Z",
  "end_time": "2025-04-01T10:30:00Z",
  "fallback": "https://calendar.google.com/calendar/event?action=TEMPLATE",
  "postback": "calendar_service_added"
}

Suggestion Responses on Webhooks

When a user taps any suggestion, the interaction is posted to your webhook. Suggested replies produce a suggestion.type: "reply" event, while suggested actions produce a suggestion.type: "action" event. Location sharing produces a separate type: "location" event.

Use the postback value to identify which suggestion the user interacted with and route your business logic accordingly. See RCS Webhooks — Suggestion Interactions for complete webhook payload details.