# 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 %}