About Template Structured Message

Last updated: 2024-04-17Contributors
Edit this page

This structured content provides some buttons associated with a message. See Channel capabilities to know on which channel you can use this structured message.

Request Example

curl -X POST "https://[YOUR DOMAIN].api.digital.ringcentral.com/1.0/contents"
{
  "source_id": "<source_id>",
  "in_reply_to_id": "<in_reply_to_id>",
  "structured_content": {
    "type": "template",
    "attachment_id": "<attachment_id>",
    "attachment_fallback_id": "<attachment_id>",
    "title": "Ringcentral, Inc.",
    "subtitle": "Cloud Business Communications.",
    "url": "github://github.com/ringcentral",
    "url_fallback": "https://github.com/ringcentral",
    "url_text": "Github",
    "items": [
      { "title": "Go to website", "type": "url", "url": "github://github.com/ringcentral", "url_fallback": "https://github.com/ringcentral" },
      { "title": "Ok", "type": "reply" },
      { "title": "Give me more", "type": "reply", "payload": "more" }
    ]
  }
}

Primary Parameters

API Property Type Description
source_id String Optional. ID of the source. Most interactions are in reply to a message being sent to the agent. In these cases, the source ID is not required.
in_reply_to_id String ID of the message being replied to.
structured_content Object Payload of the structured message.
Structured Content Settings
structured_content.type String Type of the structured message. Must be "template".
structured_content.title String Title of the template. Limited to 350 characters. If the device does not support structured messages, this field will be sent as the message.
structured_content.subtitle String Optional. Subtitle of the template. Limited to 1000 characters.
structured_content.url String Optional. Allows to redirect to this url when clicking on the image or message of the template. Limited to 2048 characters. Should only have http and https schemes.
structured_content.url_fallback String Optional. Fallback in case the url is invalid. Limited to 2048 characters. Only http and https schemes.
structured_content.url_text String Optional. Text that will be displayed instead of the hostname of the url. Automatically gets populated as the hostname of the url if blank. This field is only displayed if the url field is present. Limited to 80 characters.
structured_content.attachment_id String Optional. Existing attachment id used to decorate the template with an image. Should be public. Should be jpg, jpeg or png. Should be less than 5MB. Upload attachments for you own custom images.
structured_content.attachment_fallback_id String Optional. Fallback in case the attachment related to the attachment_id doesn’t meet the source requirements. Must be public. Only jpg, jpeg, png formats. Maximum size of 5 MB. Upload attachments for you own custom images.
structured_content.items Array List of items representing the buttons presented to the customer. A maximum of 4 items is supported.
Item Settings
structured_content.items.type String The type of the button. Can be url or reply.
structured_content.items.title String The title of the item. Limited to 80 characters.
structured_content.items.payload String Optional when the type is "reply". Ignored when the type is "url". Payload that will be returned with the structured response. Limited to 1000 characters. Can only contain ASCII characters.
structured_content.items.url String Required when the type is "url". Ignored when the type is "reply". Url to which the user will be redirected to when clicking on the item. Limited to 2048 characters. Should only have http and https schemes.
structured_content.items.url_fallback String Optional Fallback in case the url is invalid. Limited to 2048 characters. Only http and https schemes.

Example: Facebook Messenger

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example. If the template only has a title and items, it will be converted to a Button Template in Facebook Messenger.

Button Template

API Property Specificity
structured_content.title Limited to 640 characters.
structured_content.items A maximum of 3 items is supported.
structured_content.items.title Truncated to 20 characters.
structured_content.items.payload Limited to 1000 characters. Automatically gets populated as a random hex if blank.

Otherwise, it will be converted to a Generic Template in Facebook Messenger.

Generic Template

API Property Specificity
structured_content.attachment_id Supports bmp, gif, jpg, jpeg, png formats. Supports private attachments. Upload attachments for you own custom images.
structured_content.url_text Ignored property.
structured_content.items A maximum of 3 items is supported.
structured_content.title Truncated to 80 characters.
structured_content.subtitle Truncated to 80 characters.
structured_content.items.title Truncated to 20 characters.
structured_content.items.payload Limited to 1000 characters. Automatically gets populated as a random hex if blank.

Example: RingCX Messaging

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Specificity
structured_content.attachment_id Supports gif, jpg, jpeg, png formats. Supports private attachments. Upload attachments for your own custom images.
On RingCX Messaging Web, if the width of the image is bigger than the height, it will be displayed with a 5:3 ratio. Otherwise, a 1:1 ratio will be used.
Minimal recommended size with a 1:1 ratio: 258x258
Minimal recommended size with a 5:3 ratio: 258x155
structured_content.url Deep links are supported.
structured_content.target Optional. Ignored when the url is empty. Behavior applied when clicking on the url. Can be webview to open url on a webview above the chat, open to open url in new tab, or current to open url in current tab. Defaults to open when not specified. On iOS and Android, current value opens a full sized webview.
structured_content.webview_height Optional. Ignored when target is other than webview. Size of the webview used to open the link. Can be full, tall or compact. Defaults to full if unset.
structured_content.items.target Optional when the type is url. Ignored when the type is reply. Behavior applied when clicking on the item link. Can be webview to open on a webview above the chat, open to open in new tab, or current to open in current tab. Defaults to open when not specified. On iOS and Android, current value opens a full sized webview.
structured_content.items.webview_height Optional. Ignored when target is other than webview. Size of the webview used to open the link. Can be full, tall or compact. Defaults to full if unset.

Example: Google Business Messages (Rich Card)

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Specificity
structured_content.title Truncated to 200 characters.
structured_content.url Ignored property.
structured_content.url_text Ignored property.
structured_content.items.title Truncated to 25 characters.
structured_content.items.payload Automatically gets populated as a random hex if blank.
structured_content.attachment_id Supports private attachments.

Example: WhatsApp (Reply Buttons)

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Type Specificity
If subtitle is present
structured_content.title String Truncated to 60 UTF-16 code units.
structured_content.subtitle String Truncated to 963 UTF-16 code units if an attachment is present.
If subtitle is empty
structured_content.title String Limited to 1000 characters.
Truncated to 1000 UTF-16 code units.
Used as the message body.
Structured Content Settings
structured_content.attachment_id String Supports jpg, jpeg, png, mp4 formats. Supports private attachments. Upload attachments for your own custom images or videos. Should be less than 64 MB. WhatsApp supports videos with only H.264 and AAC codecs and a single audio stream.
structured_content.footer String Optional. Limited to 60 UTF-16 code units.
structured_content.url String Ignored property.
structured_content.url_fallback String Ignored property.
structured_content.url_text String Ignored property.
Item Settings
structured_content.items Array Truncated to 3 elements.
structured_content.items.type String Only reply is supported.
structured_content.items.title String Truncated to 20 charactes.
Truncated to 20 UTF-16 code units.
structured_content.items.payload String Limited to 256 characters.
Automatically gets populated as a random hex if blank.
structured_content.items.url String Ignored property.
structured_content.items.url_fallback String Ignored property.

Example: Instagram Messaging

Properties Unique to this Channel

Primary parameters are used by default, however, some parameters are unique or overwritten by parameters specific to this example.

API Property Specificity
structured_content.attachment_id Supports bmp, gif, jpg, png formats. Supports private attachments. Upload attachments for you own custom images.
structured_content.url_text Truncated to 20 characters.
structured_content.items A maximum of 3 items is supported.
structured_content.title Truncated to 80 characters.
structured_content.subtitle Truncated to 80 characters.
structured_content.items.title Truncated to 20 characters.
structured_content.items.payload Limited to 1000 characters. Automatically gets populated as a random hex if blank.