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	Conditional	—	maxItems: 4 (for RCS rich cards)	Interactive buttons.
quickReplies	array of QuickReply | null	Conditional	—	maxItems: 11	Suggested reply chips.
carousel	array of RichCard	Conditional	—	minItems: 2, maxItems: 10	Horizontally scrollable rich card sequence.
richCard	RichCardConfig	Conditional	—	—	Layout configuration for a standalone rich card.

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.

Channel-Specific Limits

Feature	RCS	DSC	DLC
Text max length	3072 chars	1,600 chars MMS, 160 chars SMS segment	1,600 chars MMS, 160 chars SMS segment
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

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.

Text Message

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

text-message.json

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

Media Message

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

media-message.json

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

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	—

buttons.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": "[phone]"
    },
    {
      "type": "viewLocation",
      "title": "Find nearest store",
      "query": "Acme Store New York"
    }
  ]
}

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

quick-replies.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"
    }
  ]
}

Carousel

A carousel is a horizontally scrollable sequence of 2–10 RichCard objects.

A carousel array MUST contain a minimum of 2 items and a maximum of 10 items. Arrays outside this range are invalid.

carousel.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"
            }
          ]
        }
      ]
    }
  }
}

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 | 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.

Each RichCard MUST satisfy at least one of: title present, description present, or media present. A card with none of these fields is invalid.

RichCardConfig

The richCard property on a Message 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.

richcard-config.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"
        }
      ]
    }
  }
}