# Messages

The **Message** object defines the content delivered to the user during a `send` action. A message MUST contain at least one of the following content fields: `text`, `media`, `mediaType`+`media`, `buttons`, `quickReplies`, `carousel`, `richCard`, or `title`.

## Message Properties

| Property       | Type                                       | Required    | Default | Constraints                       | Description                                                                |
| -------------- | ------------------------------------------ | ----------- | ------- | --------------------------------- | -------------------------------------------------------------------------- |
| `text`         | string                                     | Conditional | —       | maxLength: 3072                   | Message body text. At least one content field must be present.             |
| `title`        | string                                     | Conditional | —       | maxLength: 200                    | Message title. Satisfies the content requirement alone.                    |
| `mediaType`    | string                                     | Conditional | —       | `image`, `video`, `audio`, `file` | Type of media attachment. Required when `media` is also intended as typed. |
| `media`        | string                                     | Conditional | —       | format: uri                       | URL of the media file. Can be used alone or with `mediaType`.              |
| `buttons`      | array of [Button](#button)                 | Conditional | —       | maxItems: 4 (for RCS rich cards)  | Interactive buttons.                                                       |
| `quickReplies` | array of [QuickReply](#quickreply) \| null | Conditional | —       | maxItems: 11                      | Suggested reply chips.                                                     |
| `carousel`     | array of [RichCard](#richcard)             | Conditional | —       | minItems: 2, maxItems: 10         | Horizontally scrollable rich card sequence.                                |
| `richCard`     | [RichCardConfig](#richcardconfig)          | Conditional | —       | —                                 | Layout configuration for a standalone rich card.                           |

{% hint style="danger" %}
A Message object MUST satisfy at least one of these `anyOf` requirements: `text` present, `mediaType`+`media` present, `media` present alone, `carousel` present, `buttons` present, `quickReplies` present, `richCard` present, or `title` present. An empty message object is invalid.
{% endhint %}

## Channel-Specific Limits

| Feature                   | RCS                       | DSC                                                 | DLC                                                 |
| ------------------------- | ------------------------- | --------------------------------------------------- | --------------------------------------------------- |
| Text max length           | 3072 chars                | <p>1,600 chars MMS,</p><p>160 chars SMS segment</p> | <p>1,600 chars MMS,</p><p>160 chars SMS segment</p> |
| Buttons per message       | 4                         | N/A                                                 | N/A                                                 |
| Quick replies             | Up to 11                  | N/A                                                 | N/A                                                 |
| Carousel cards            | 2–10                      | N/A                                                 | N/A                                                 |
| List items                | 2–4                       | N/A                                                 | N/A                                                 |
| Media types               | image, video, audio, file | image, video, file                                  | image, video, file                                  |
| Rich cards                | Yes                       | No                                                  | No                                                  |
| Button title max          | 25 chars                  | N/A                                                 | N/A                                                 |
| Quick reply title max     | 25 chars                  | N/A                                                 | N/A                                                 |
| Rich card title max       | 200 chars                 | N/A                                                 | N/A                                                 |
| Rich card description max | 2000 chars                | N/A                                                 | N/A                                                 |

{% hint style="warning" %}
Features listed as "N/A" for DLC are silently degraded or omitted when the experience runs on a DLC channel. Design cross-channel experiences with a `channel` action restriction or `channelTypes` condition to serve appropriate content per channel.
{% endhint %}

## Text Message

The simplest message form. The `text` field is the only required content.

{% code title="text-message.json" %}

```json
{
  "send": {
    "message": {
      "text": "Your order ACM-12345 has been shipped. Estimated arrival: March 3, 2025."
    }
  }
}
```

{% endcode %}

## Media Message

A message with a media attachment. `media` is the attachment URL. `mediaType` hints at the type for rendering.

{% code title="media-message.json" %}

```json
{
  "send": {
    "message": {
      "text": "Here is your receipt:",
      "mediaType": "file",
      "media": "https://cdn.acme.com/receipts/ACM-12345.pdf"
    }
  }
}
```

{% endcode %}

Accepted `mediaType` values:

| Value     | Description                         |
| --------- | ----------------------------------- |
| `"image"` | JPEG/JPG, PNG, GIF                  |
| `"video"` | H.263, M4V, MP4, MPEG, MPEG-4, WebM |
| `"audio"` | MP3, OGG, WAV, ACC, MPEG, MP4, 3GPP |
| `"file"`  | PDF                                 |

## Button

A **Button** is an interactive element attached to a message. The required fields depend on the button type.

### Button Properties

| Property          | Type           | Required    | Default | Constraints            | Description                                                                                                |
| ----------------- | -------------- | ----------- | ------- | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
| `type`            | string         | **Yes**     | —       | See enum               | Button type.                                                                                               |
| `title`           | string         | Conditional | —       | maxLength: 25          | Display label. Required for `weburl`, `postback`, `call`.                                                  |
| `payload`         | string         | Conditional | —       | maxLength: 1000        | URL for `weburl`, phone for `call`, custom data for `postback`. Required for `weburl`, `postback`, `call`. |
| `execute`         | string \| null | No          | —       | —                      | Workflow or action to execute on click (postback buttons).                                                 |
| `postbackData`    | string \| null | No          | —       | —                      | Postback data sent on click.                                                                               |
| `description`     | string \| null | No          | —       | —                      | Descriptive text for the button.                                                                           |
| `application`     | string \| null | No          | —       | —                      | Application identifier.                                                                                    |
| `webviewViewMode` | string         | No          | —       | `FULL`, `HALF`, `TALL` | Webview display mode.                                                                                      |
| `eventTitle`      | string         | No          | —       | —                      | Calendar event title (calendar type).                                                                      |
| `startTime`       | string         | No          | —       | ISO 8601               | Calendar event start (calendar type).                                                                      |
| `endTime`         | string         | No          | —       | ISO 8601               | Calendar event end (calendar type).                                                                        |
| `query`           | string         | No          | —       | —                      | Location search query (viewLocation type).                                                                 |
| `latLong`         | object         | No          | —       | —                      | `{ latitude, longitude }` (viewLocation type).                                                             |
| `label`           | string         | No          | —       | —                      | Location label (viewLocation type).                                                                        |
| `theme`           | object         | No          | —       | —                      | Button theme configuration.                                                                                |

### Button Types and Required Fields

| Type           | `title`          | `payload`               | Additional Required Fields                       |
| -------------- | ---------------- | ----------------------- | ------------------------------------------------ |
| `weburl`       | **Yes** (max 25) | **Yes** (URL, max 1000) | —                                                |
| `postback`     | **Yes** (max 25) | **Yes** (max 1000)      | —                                                |
| `call`         | **Yes** (max 25) | **Yes** (phone number)  | —                                                |
| `text`         | No               | No                      | —                                                |
| `location`     | No               | No                      | —                                                |
| `viewLocation` | No               | No                      | `query` or `latLong` recommended                 |
| `calendar`     | No               | No                      | `eventTitle`, `startTime`, `endTime` recommended |
| `datetime`     | No               | No                      | —                                                |

{% code title="buttons.json" %}

```json
{
  "buttons": [
    {
      "type": "weburl",
      "title": "Track shipment",
      "payload": "https://tracking.acme.com/ACM-12345"
    },
    {
      "type": "postback",
      "title": "Cancel order",
      "payload": "cancel_ACM-12345",
      "execute": "cancel-order-workflow"
    },
    {
      "type": "call",
      "title": "Call support",
      "payload": "+18005551234"
    },
    {
      "type": "viewLocation",
      "title": "Find nearest store",
      "query": "Acme Store New York"
    }
  ]
}
```

{% endcode %}

## QuickReply

**Quick replies** are suggested response chips displayed below a message. Up to 11 MAY be included.

### QuickReply Properties

| Property          | Type           | Required    | Default | Constraints            | Description                                              |
| ----------------- | -------------- | ----------- | ------- | ---------------------- | -------------------------------------------------------- |
| `type`            | string         | **Yes**     | —       | See enum               | Quick reply type.                                        |
| `title`           | string         | Conditional | —       | maxLength: 25          | Display label. Required for `text` and `postback` types. |
| `payload`         | string         | No          | —       | maxLength: 1000        | Data sent when selected.                                 |
| `execute`         | string \| null | No          | —       | —                      | Workflow or action to execute on selection.              |
| `postbackData`    | string \| null | No          | —       | —                      | Postback data.                                           |
| `webviewViewMode` | string         | No          | —       | `FULL`, `HALF`, `TALL` | Webview mode.                                            |
| `application`     | string \| null | No          | —       | —                      | Application identifier.                                  |

### Quick Reply Types and Required Fields

| Type           | `title` Required | Description                                      |
| -------------- | ---------------- | ------------------------------------------------ |
| `text`         | **Yes**          | Text chip that sends its title as user input     |
| `postback`     | **Yes**          | Sends payload without displaying as user message |
| `location`     | No               | Prompts user to share location                   |
| `viewLocation` | No               | Opens map view                                   |
| `calendar`     | No               | Opens calendar picker                            |
| `weburl`       | No               | Opens a URL                                      |
| `call`         | No               | Initiates a phone call                           |
| `datetime`     | No               | Opens datetime picker                            |

{% code title="quick-replies.json" %}

```json
{
  "quickReplies": [
    {
      "type": "text",
      "title": "Yes, confirm",
      "payload": "confirm_yes",
      "execute": "confirm-order"
    },
    {
      "type": "text",
      "title": "No, cancel",
      "payload": "confirm_no",
      "execute": "cancel-order"
    },
    {
      "type": "location",
      "title": "Share my location"
    }
  ]
}
```

{% endcode %}

## Carousel

A **carousel** is a horizontally scrollable sequence of 2–10 [RichCard](#richcard) objects.

{% hint style="danger" %}
A `carousel` array MUST contain a minimum of 2 items and a maximum of 10 items. Arrays outside this range are invalid.
{% endhint %}

{% code title="carousel.json" %}

```json
{
  "send": {
    "message": {
      "carousel": [
        {
          "title": "Acme Pro Running Shoe",
          "description": "Lightweight carbon-fiber sole. Available in 8 colors.",
          "media": "https://cdn.acme.com/products/pro-runner.jpg",
          "mediaType": "image",
          "mediaHeight": "MEDIUM",
          "buttons": [
            {
              "type": "weburl",
              "title": "Shop now",
              "payload": "https://shop.acme.com/pro-runner"
            },
            {
              "type": "postback",
              "title": "Add to cart",
              "payload": "cart_add_pro-runner",
              "execute": "add-to-cart"
            }
          ]
        },
        {
          "title": "Acme Trail Blazer",
          "description": "All-terrain grip. Waterproof membrane. 6mm lug depth.",
          "media": "https://cdn.acme.com/products/trail-blazer.jpg",
          "mediaType": "image",
          "mediaHeight": "MEDIUM",
          "buttons": [
            {
              "type": "weburl",
              "title": "Shop now",
              "payload": "https://shop.acme.com/trail-blazer"
            },
            {
              "type": "postback",
              "title": "Add to cart",
              "payload": "cart_add_trail-blazer",
              "execute": "add-to-cart"
            }
          ]
        }
      ]
    }
  }
}
```

{% endcode %}

## RichCard

A **RichCard** is a single card in a carousel. At least one of `title`, `description`, or `media` MUST be present.

### RichCard Properties

| Property          | Type                               | Required    | Default | Constraints                       | Description                           |
| ----------------- | ---------------------------------- | ----------- | ------- | --------------------------------- | ------------------------------------- |
| `title`           | string \| null                     | Conditional | —       | maxLength: 200                    | Card title.                           |
| `description`     | string \| null                     | Conditional | —       | maxLength: 2000                   | Card body text.                       |
| `media`           | string \| null                     | Conditional | —       | —                                 | Media URL (image, GIF, video, PDF).   |
| `mediaType`       | string                             | No          | —       | `image`, `video`, `audio`, `file` | Media type hint.                      |
| `buttons`         | array of [Button](#button) \| null | No          | —       | maxItems: 4                       | Action buttons on the card.           |
| `cardOrientation` | string \| null                     | No          | —       | `VERTICAL`, `HORIZONTAL`          | Card layout orientation.              |
| `mediaHeight`     | string \| null                     | No          | —       | `SHORT`, `MEDIUM`, `TALL`         | Media area height.                    |
| `imageAlignment`  | string \| null                     | No          | —       | `LEFT`, `RIGHT`                   | Image alignment for horizontal cards. |
| `thumbnailUrl`    | string \| null                     | No          | —       | —                                 | Thumbnail URL for video content.      |

{% hint style="danger" %}
Each RichCard MUST satisfy at least one of: `title` present, `description` present, or `media` present. A card with none of these fields is invalid.
{% endhint %}

## RichCardConfig

The `richCard` property on a [Message](#message-properties) provides layout configuration for a standalone rich card message.

### RichCardConfig Properties

| Property          | Type           | Required | Default | Constraints               | Description                              |
| ----------------- | -------------- | -------- | ------- | ------------------------- | ---------------------------------------- |
| `cardOrientation` | string \| null | No       | —       | `VERTICAL`, `HORIZONTAL`  | Card layout orientation.                 |
| `mediaHeight`     | string \| null | No       | —       | `SHORT`, `MEDIUM`, `TALL` | Media area height.                       |
| `imageAlignment`  | string \| null | No       | —       | `LEFT`, `RIGHT`           | Image alignment (horizontal cards only). |
| `thumbnailUrl`    | string \| null | No       | —       | —                         | Thumbnail URL for media.                 |

{% code title="richcard-config.json" %}

```json
{
  "send": {
    "message": {
      "title": "Acme Spring Sale",
      "text": "Up to 40% off select items this weekend only.",
      "media": "https://cdn.acme.com/banners/spring-sale-2025.jpg",
      "mediaType": "image",
      "richCard": {
        "cardOrientation": "VERTICAL",
        "mediaHeight": "TALL"
      },
      "buttons": [
        {
          "type": "weburl",
          "title": "Shop the sale",
          "payload": "https://shop.acme.com/sale"
        }
      ]
    }
  }
}
```

{% endcode %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://playbook.nativemsg.com/rcs-experience-schema/reference/messages.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.