Supported RCS message types

Naxai RCS supports four message types: text, file, rich card and carousel. This page explains what each one can contain, its limits, and which media formats to use so your content displays well on both Android and iOS.

Overview

Every message type can be combined with suggestions: tappable replies and actions displayed with the message.

Text

A plain text message, the RCS equivalent of an SMS but without the 160-character segment limit.

{
  "to": "32478123456",
  "message": {
    "type": "text",
    "text": "Hello world with suggestions!"
  },
  "suggestions": [
    {
      "type": "reply",
      "text": "Want more info?",
      "postbackData": "more"
    },
    {
      "type": "action",
      "text": "Call us",
      "postbackData": "call",
      "action": {
        "type": "dialAction",
        "phoneNumber": "3223342323"
      }
    }
  ]
}

File

Sends a single image, video or document. The recipient's device displays it inline (images and videos) or as a downloadable file (PDF).

{
  "to": "32478123456",
  "message": {
    "type": "file",
    "file": {
      "fileUrl": "https://www.example.com/image.png",
      "thumbnailUrl": "https://www.example.com/image-thumbnail.png",
      "forceRefresh": false
    }
  }
}

Rich card

A rich card groups media, a title, a description and up to 4 suggestions in a single message bubble. It is the best format for promotions, order updates, or any message that benefits from an image and a clear call to action.

A rich card can have two layouts, set with cardOrientation:

{
  "to": "32478123456",
  "message": {
    "type": "standaloneRichCard",
    "cardOrientation": "VERTICAL",
    "cardContent": {
      "title": "Rich Card",
      "description": "This is a standalone rich card content",
      "media": {
        "height": "TALL",
        "contentInfo": {
          "fileUrl": "https://www.example.com/image.png",
          "thumbnailUrl": "https://www.example.com/image-thumbnail.png",
          "forceRefresh": false
        }
      },
      "suggestions": [
        {
          "type": "action",
          "text": "Shop now",
          "postbackData": "shop_now",
          "action": {
            "type": "openUrlAction",
            "url": "https://www.example.com"
          }
        },
        {
          "type": "reply",
          "text": "I like RCS",
          "postbackData": "like1"
        }
      ]
    }
  }
}

Carousel

A carousel is a row of rich cards the recipient swipes horizontally. Use it to present several products, offers or options in a single message.

{
  "to": "32478123456",
  "message": {
    "type": "carouselRichCard",
    "cardWidth": "MEDIUM",
    "cardContents": [
      {
        "title": "Title 1",
        "description": "Description card 1",
        "media": {
          "height": "MEDIUM",
          "contentInfo": {
            "fileUrl": "https://www.example.com/video.mp4",
            "thumbnailUrl": "https://www.example.com/image.png",
            "forceRefresh": false
          }
        },
        "suggestions": [
          { "type": "reply", "text": "Like", "postbackData": "like_1" }
        ]
      },
      {
        "title": "Title 2",
        "description": "Description card 2",
        "media": {
          "height": "MEDIUM",
          "contentInfo": {
            "fileUrl": "https://www.example.com/image.png",
            "thumbnailUrl": "https://www.example.com/image.png",
            "forceRefresh": false
          }
        },
        "suggestions": [
          { "type": "reply", "text": "Like", "postbackData": "like_2" }
        ]
      }
    ]
  }
}

Suggestions

Suggestions are tappable buttons that guide the recipient through the conversation, using features already available on their device. There are two kinds:

• Suggested replies send a predefined answer back to your Agent.
• Suggested actions trigger something on the recipient's device: open a website, call a number, show or share a location, or create a calendar event.

When the recipient taps a suggestion, your Agent receives an event with the suggestion text and its postbackData. See Receiving RCS Messages.

Where suggestions appear

Common fields

All suggestions share these fields:

Available suggestions

Suggested reply

A pre-written answer the recipient can send with one tap, instead of typing. Use it to steer the conversation ("Yes" / "No", "Track my order", "Talk to an agent").

{
  "type": "reply",
  "text": "Track my order",
  "postbackData": "track_order"
}

Open URL

Opens the recipient's default browser at the given URL. If the URL is a deep link to an installed app, that app opens instead.

{
  "type": "action",
  "text": "Shop now",
  "postbackData": "shop_now",
  "action": {
    "type": "openUrlAction",
    "url": "https://www.example.com/offers"
  }
}

Open URL in a webview

Opens the web page inside the messaging app, on top of the conversation, instead of switching to the browser. The recipient stays in the conversation, which works well for forms, checkouts or booking pages. If the device doesn't support webviews, the URL opens in the default browser.

{
  "type": "action",
  "text": "Book a slot",
  "postbackData": "book_slot",
  "action": {
    "type": "openUrlAction",
    "url": "https://www.example.com/booking",
    "application": "WEBVIEW",
    "webviewViewMode": "TALL",
    "description": "Booking form for your appointment"
  }
}

Dial phone

Opens the recipient's dialer with your number pre-filled. The recipient still confirms the call.

{
  "type": "action",
  "text": "Call us",
  "postbackData": "call",
  "action": {
    "type": "dialAction",
    "phoneNumber": "3223342323"
  }
}

View location

Opens the recipient's default map app with a pin on the location you specify, for example your shop or a pick-up point.

{
  "type": "action",
  "text": "Find our store",
  "postbackData": "view_store",
  "action": {
    "type": "viewLocationAction",
    "latitude": 50.8466,
    "longitude": 4.3528,
    "label": "Naxai Store Brussels"
  }
}

Share location

Opens the location picker on the recipient's device so they can send you their location, for example to find the nearest store or organise a delivery. The location is sent to your Agent as an inbound message.

{
  "type": "action",
  "text": "Share my location",
  "postbackData": "share_location",
  "action": {
    "type": "shareLocationAction"
  }
}

Create calendar event

Opens the recipient's calendar app with a new event pre-filled. Use it for appointments, deliveries or events.

{
  "type": "action",
  "text": "Add to calendar",
  "postbackData": "add_calendar",
  "action": {
    "type": "createCalendarEventAction",
    "startTime": "2026-10-15T09:00:00Z",
    "endTime": "2026-10-15T09:30:00Z",
    "title": "Appointment at Naxai Store",
    "description": "Your appointment is confirmed. See you soon!"
  }
}

Best practices

• One main action, then replies: use one suggested action as your main call to action, placed first, followed by up to 3 suggested replies. This renders consistently on Android and iOS.
• Don't mix card and message suggestions: after a rich card or carousel, avoid adding message-level suggestions. iOS merges them into the card, while Android keeps them separate.
• Keep labels short and explicit: "Book now" works better than "Click here". Labels longer than 25 characters are rejected.
• Icons are automatic: the device adds an icon to each action (phone, map, calendar...). You can't customise it.

Media specifications

General requirements

These apply to every media file you send, in file messages, rich cards and carousels:

• Public URL: fileUrl and thumbnailUrl must be publicly reachable over HTTPS, without authentication.
• Correct content type: the file type is detected from the Content-Type header returned by your server, so it must be present and accurate.
• File size: up to 100 MB per file. Smaller files load faster, so aim for a few hundred kB for images.
• Thumbnail: up to 100 kB, JPEG, PNG or GIF. Recommended for videos and large images.
• Caching: files are cached after the first fetch. If you replace a file at the same URL, set forceRefresh to true, or use a new URL.
• Animated GIFs: supported on Android, but displayed as a still image on iOS.

Recommended formats (Android and iOS)

Android and iOS display card media differently: Android crops media to a fixed height, while iOS generally keeps the original ratio. The formats below give the most consistent result on both platforms. Use them by default.

All media heights (Android reference)

If you target other card sizes, use the ratios below. They show the media in full on Android, without cropping. On iOS, media keeps its original ratio, so results may differ: always test on real devices.

Vertical rich card

Carousel, cardWidth: SMALL

Carousel, cardWidth: MEDIUM

Sizes are based on Full HD (1080p) screens. You can divide them by 3 (for example 540 × 360 px instead of 1620 × 1080 px) to reduce file size, keeping the same ratio.

If your media doesn't match the ratio of the selected height, Android crops it from the centre.

Tips for reliable rendering

• Keep text short: on Android, a long title and description reduce the space left for media in horizontal cards. On iOS, a card whose text exceeds 6 lines becomes tappable to open the full text, and the media is not shown in that view. Aim for 3 lines of title and description.
• Don't put critical text in the image only: font size settings and screen rotation can crop media. Repeat important information in the title or description.
• Test before launch: rendering depends on the device, OS version and user settings. Send your messages to test devices first, see Testing RCS Messages.

Not supported

Google Wallet actions (adding a pass, loyalty card or ticket to the recipient's wallet) are not currently available with Naxai.

What's next

• Sending RCS Messages via API — suggestions, message traffic types, and revoking a message
• RCS Broadcasts — send these message types in bulk
• Testing RCS Messages — preview messages on real devices before launch
• Send RCS message API reference — full request and response details