Getting Started with Rich Messaging — Introduction

Rich Messaging allows you to push something more rich and interactive than just plain text to existing messaging channels. This is achieved by using the Conversational Cloud Structured Content Framework.

For a list of Rich Messaging capabilities for each channel, see the Rich Messaging Channel Capabilities table.

What is Structured Content

Most conversations involve plain text like what you are reading now. However, sometimes you may want to send content (images, buttons, maps, quick replies, etc) to a consumer in a more rich, interactive, and structured format. This is achieved with structured content templates.

Carousel

For example, rather than sending an address to a location, you can send a picture of the location on a map that links out to a map application.

In order to achieve this behavior, you must send information in a structured format that can be interpreted and rendered by Conversational Cloud. The most common format is JSON (Javascript Object Notation).

So, rather than sending to a consumer the text 1234 Hollywood Boulevard, Los Angeles, CA, you would send the address in JSON format like below:

{
  "text": yourBusinessName,
  "type": "vertical",
  "elements": [
    {
      "type": "map",
      "lo": yourLongitude,
      "la": yourLatitude,
      "tooltip": "Map",
      "click": {
        "actions": [
          {
            "type": "navigate",
            "name": "navigate",
            "lo": yourLongitude,
            "la": yourLatitude
          }
        ]
      }
    },
    {
      "type": "text",
      "text": "1234 Hollywood Boulevard, Los Angeles, CA"
    },
  ],
  "metadata": { "fallback": url_link_map_link }
}

This JSON format is called a template. Every template contains elements (in this case, "map" and "text").

LivePerson provides templates and common elements for all rich messaging enabled channels.

How to Send Structured Content to the Conversation

How a structured content template is sent to a consumer is different depending if it is sent by a human or bot agent.

Human Agent

With a human agent, you will need to implement a new widget based on the Agent Workspace Widget SDK.

You will use the writeSC command to push the template to the conversation from the widget. Below is example code of what the widget would need at the minimum for our example.

var notifyWhenDone = function(err) {
    if (err) {
        // Do something with the error
    }
    // called when the command is completed successfully,
    // or when the action terminated with an error.
};

var cmdName = lpTag.agentSDK.cmdNames.writeSC; // = "Write StructuredContent"
var data = {
  json: {
    "text": yourBusinessName,
    "type": "vertical",
    "elements": [
      {
        "type": "map",
        "lo": yourLongitude,
        "la": yourLatitude,
        "tooltip": "Map",
        "click": {
          "actions": [
            {
              "type": "navigate",
              "name": "navigate",
              "lo": yourLongitude,
              "la": yourLatitude
            }
          ]
        }
      },
      {
        "type": "text",
        "text": "1234 Hollywood Boulevard, Los Angeles, CA"
      },
    ],
    "metadata": { "fallback": url_link_map_link }
  },
  metadata: [	//metadata is optional
			{"type":"ExternalId","id":"running364"},
			{"type":"ExternalId","id":"soccer486"}
		]
};

lpTag.agentSDK.command(cmdName, data, notifyWhenDone);

Continuing with the map example, the agent widget would contain a text property that allows the agent to enter an address and click a "send" button. This "send" button would:

convert the address to the correct template with the desired elements
send the template to the consumer with the writeSC command

For further information, refer to the Developer Community documentation.

Bot Agent

You will need to set up a bot integration using the Messaging Agent SDK.

For more general information about using the SDK to integrate bots, please refer to the Solution’s documentation.

Once the bot exists, you will perform the same transformation as with the Agent Workspace Widget:

convert the data to the correct template with the desired elements
send the template to the consumer with the Agent Workspace SDK command

Below is an example of sending the same location map.

agent.publishEvent({
	dialogId: 'MY_DIALOG_ID',
	event: {
		type: 'RichContentEvent',
		content: {
      "text": yourBusinessName,
      "type": "vertical",
      "elements": [
        {
          "type": "map",
          "lo": yourLongitude,
          "la": yourLatitude,
          "tooltip": "Map",
          "click": {
            "actions": [
              {
                "type": "navigate",
                "name": "navigate",
                "lo": yourLongitude,
                "la": yourLatitude
              }
            ]
          }
        },
        {
          "type": "text",
          "text": "1234 Hollywood Boulevard, Los Angeles, CA"
        },
      ],
      "metadata": { "fallback": url_link_map_link }
    }
	}
}, null, [{type: 'ExternalId', id: 'MY_CARD_ID'}]);  // ExternalId is how this card will be referred to in reports

// Success response: {"sequence":29}

Please refer to the SDK’s repository for more examples.

Templates

LivePerson provides multiple structured content templates for each unique rich messaging enabled channel. See a list of rich messaging channels and their capabilities in Channel Capabilities.

In order to handle the differences in channel rendering, these templates abstract away the unique feel of each channel and allow you to implement common elements in a familiar way.

Each structured content template will contain one or more elements in the elements array seen in the example below:

Example

{
  "type": "type",
  "tag": "tag",
  "elements": [
    // Basic elements here
  ]
}

Properties

Property Name	Description	Type	Required
type	Type of template. Often used to specify arrangement like "vertical" or "horizontal"	Enum	Y
border	Type of border. "border" (default) or "borderLess" or "dropShadow"	Enum	N
tag	Further specifies the template type	String	N
elements	List of element objects	Array	Y

All templates will consist of an object that holds the elements array. The object will always have a type and optionally have a tag. The tag is only relevant when using third party connectors like Facebook Messenger, Apple Messages for Business, etc.

There is an additional property for Horizontal type only:

Property Name	Description	Type	Required
percentages	Array of percentages (integer) for each element in the elements list. If not specified, area will divided equally between the elements	Array	N

Example

{
  "type": "horizontal",
  "border": "borderLess",
  "percentages": [30, 70],
  "elements": [
    // Basic element here,
    // Basic element here
  ]
}

Below you will find basic elements, their styling, and their click operations, that are common within all templates.

When you are comfortable with the basic elements, you can see them in action in the various templates for Mobile SDK and Web, Facebook Messenger, Apple Messages for Business, etc.

Basic Elements

Basic elements are the core components of the structured content framework. By using these elements in your template, you can send basic messages, such as simple text, images or buttons.

You can also send a Structured Content template which includes multiple basic elements with attached actions, creating a more complex and interactive template.

See the types of basic elements supported by the framework below:

Button

A simple Button which triggers an Action when clicked.

Properties

Property Name	Description	Type	Required	Size Limit
type	Type of element. Must be 'button'	Enum	Y
class	Look and feel of the button. Default is text	Enum — text/button	N
title	Button title	String	Y	128 chars
click	On-click operation (included metadata and/or actions clauses)		Y
tooltip	Button tooltip, used also as aria	String	N	256 chars
style	Styling elements	Container	N
rtl	This parameter changes the direction of text only from left to right to right to left (for languages like Hebrew, Arabic, Urdu, etc). Default is false.	Boolean	N

For the 'click' property, please see the Click Operations section.

For the 'style' property, please see the Rich Messaging Basic Elements Styling section.

Example

{
	"type": "button",
	"title": "Push Me!",
	"click": {
		"metadata": [{
	        }],
		"actions": [{
        "type": "link",
        "name": "Add to cart",
        "uri": "https://www.example.com"
		}]
	},
	"tooltip": "button tooltip",
	"rtl": true
}

Image

You can send images by sharing a URL. Supported formats are JPG and PNG. Since, in this case, images are not stored on LivePerson servers, there is no file size limit when using images within a Structured Content image element.

Properties

Property Name	Description	Type	Required	Size Limit
type	Type of element. Must be image	Enum	Y
url	Image URL	String	Y	2048 chars
caption	Image caption	String	N	128 chars
rtl	This parameter changes the direction of text only from left to right to right to left (for languages like Hebrew, Arabic, Urdu, etc). Default is false	Boolean	N
click	On-click operation (included metadata and/or actions clauses)
tooltip	Image tooltip, used also as aria	String	N
alt	Describes the image to users	String	N	2000 chars
style	Styling elements	Container	N

For the 'click' property, please see the Click Operations section.

For the 'style' property, please see the Rich Messaging Basic Elements Styling section.

Note: Image domains must be added to a whitelist via internal LivePerson configuration (Houston). Please note that you must add all domains to this list manually as wildcards are not supported. All domains must be HTTPS secure.

Example

{
	"type": "image",
	"url": "https://cdn.bgr.com/2016/08/iphone-8-concept.jpg?quality=98&strip=all",
	"caption": "This is an example of image caption",
	"click": {
		"metadata": [{
	        }],
    "actions": [{
      "type": "link",
      "name": "Add to cart",
      "uri": "https://www.example.com"
		}]
	},
	"tooltip": "image tooltip",
	"rtl" : true
}

Map

Map that points to a specific location.

Properties

Property Name	Description	Type	Required
type	Type of element. Must be map	Enum	Y
lo	Longitude	Float	Y
la	Latitude	Float	Y
click	On-click operation (included metadata and/or actions clauses)
tooltip	Map tooltip, used also as aria	String	N
style	Styling elements	Container	N

For the 'click' property, please see the Click Operations section.

For the 'style' property, please see the Rich Messaging Basic Elements Styling section.

Example

{
	"type": "map",
  "la": 40.75620,
  "lo": -73.99861,
	"click": {
		"metadata": [{
	        }],
    "actions": [{
        "type": "navigate",
        "la": 40.75620,
        "lo": -73.99861,
		}]
	},
	"tooltip": "map tooltip"
}

Text

Simple plain text message.

Properties

Property Name	Description	Type	Required	Size Limit
type	Type of element. Must be text.	Enum	Y
text	The message	String	Y	5000 chars
tooltip	Text tooltip, used also as aria	String	N	256 chars
style	Styling elements	Container	N
rtl	This parameter changes the direction of text only from left to right to right to left (for languages like Hebrew, Arabic, Urdu, etc). Default is false.	Boolean	N

For the 'style' property, please see the Rich Messaging Basic Elements Styling section.

Example

{
	"type": "text",
	"text": "This is an example for text element",
	"tooltip": "text tooltip",
	"rtl" : true
}

Element Click Operations

An element which has an "actions" property, an on-click operation (executed when the consumer clicks on the element) and a metadata property. These elements are clickable by the consumer, resulting in an action performed on the browser or app through which the consumer is interacting with you. This action could be opening a link, a third party navigation app and more.

On-click operations can result from two object types:

Property Name	Description	Type	Required	Size Limit
Actions	List of actions to execute (Navigate/Link/publish text)	action	N	4 actions per element
Metadata	list of predefined objects to send back to the agent		N

Example

"click": {
	"metadata": [
		{
			"type": "ExternalId",
			"id": "someID"
		}
	],
	"actions": [
		{
			"type": "publishText",
			"text": "Show Plan"
		}
	]
}

Actions

Actions are a list of applicative actions that will run on the consumer side and will help them to achieve some kind of an operation. For instance: navigate with a third party navigation app to a predefined place.

Note: Only button, image and map objects can receive the actions property.

Types of actions supported by the platform:

Navigate
Link
Publish Text

Navigate

This actions has two use cases:

Web: open Google Maps with the location preselected.
Mobile: navigate to the location with a third party navigation app.

Properties

Property Name	Description	Type	Required
type	Type of action. Must be navigate	Enum	Y
lo	Longitude	Float	Y
la	Latitude	Float	Y

Example

{
	"type": "navigate",
	"lo": 40.75620,
	"la": -73.99861
}

Link

Open a URL in a web view when opened in mobile, or in a new tab for web. This action can be used for deep link purposes.

Each environment can override the URI for their specific needs.

Properties

Property Name	Description	Type	Required	Size Limit
type	Type of action. Must be link	Enum	Y
uri	The url to open	String	Y	2048 chars
target	The target attribute specifies where to open the link. Supported by Web Messaging. Default is "blank"	Enum — blank/self	N

Example

{
	"type": "link",
	"uri": "www.google.com",
	"ios": {
		"uri": "specific uri for iOS"
	},
	"android": {
		"uri": "specific uri for Android"
	},
	"web": {
		"uri": "specific uri for Web"
	},
  "target": "self"
}

Publish Text

In order to support sending a message as a response for a button click, we introduced a new action called "Publish Text". This action allows the brand to send a message on behalf of the consumer that will appear in the transcript.

This action will be used also by the clients (the Mobile Messaging App for example or Conversational Cloud's window) to send a response when a button was clicked.

Properties

Property Name	Description	Type	Required	Size Limit
type	Type of action. Must be 'publishText'	Enum	Y
text	The text to display in the transcript once the action was clicked	String	Y	5000 chars

Example

 {
   "type": "publishText",
   "text": "text to send on behalf of the consumer"
 }

Metadata

Metadata is a list of predefined objects that can be sent back to the agent / bot and be used in reporting / analysis. Metadata can be defined in the header section of the request or inside an element click object. For a more in depth guide on how metadata in Structured Content works, please refer to the Conversation Metadata guide.

When filling out the structured content template, if the metadata ExternalID is supplied, it will be returned to Conversational Cloud when the associated action is executed.

This is important for reporting on consumer interactions with the template, as well as for bot activity. A Structured Content object general ID can be defined in the <header> section of the request by using the tag. It can also be defined for each click.

You can see an example in the Messaging Agent SDK by searching for “ExternalID”.

Note: When using our APIs to communicate as a consumer (for example, by using the Messaging Window API or the Connector API), metadata should always be added to an action. This is so that our services have an indication that an element was clicked. The metadata should be sent as part of 'AcceptStatusEvent' with the assigned status of 'ACTION'. For more information on 'AcceptStatusEvent' and its status property, please see the Messaging Window API.

If the type of action is 'publishText' (see above for an example), the metadata should be attached to the 'ContentEvent' as well. This is so that a certain text which is published is associated with the click which sent it.

Element Styling

Each basic element can have specific style rules defined for it, controlling how it looks like when rendered.

Properties

Property Name	Description	Type
bold	Whether the text is bold or not	Boolean
italic	Whether the text is in italics or not	Boolean
color	Defines the element's color	String - hex color
background-color	Defines the element's background color	String - hex color
size	Defines the element's size	Enum - small/medium/large

Example

"style": {
	"bold": true,
	"italic": true,
	"color": "###453533",
	"background-color": "###3E47A0",
	"size": "small"
}

Element Accessibility Attributes

Each basic element can have specific accessibility attributes defined to them. Some of the widely used attributes are listed below. For the entire list of supported attributes, please refer to this list.

Properties

Property Name	Description
role	Describes the role of an element.
tabindex	Describes the tab navigation order of elements. Describes the tab navigation order of elements. Use only tabindex=”0” to add active elements to the taborder and tabindex=”-1” to remove active elements from the taborder. Do not use tabindex on static elements.
aria-label	Describes a string value that labels an element. Use an aria-label only on elements with an HTML or ARIA roles. Do not define an aria-label on static elements such as <div> with no role.
aria-level	Only used together with role=heading to specify the heading level of the element.
aria-describedby	Reference longer content to provide description with relevant id. Define the attribute only on active elements such as buttons and links. Do not define this attribute on static elements such as <div> with no role.
aria-labelledby	References one or more IDs of content that exists in the DOM to define the accessible name of an active element.
aria-hidden	Hide/show the element from assistive technology. Only used on static content NOT on active elements such as buttons and links.

Example

{
  "type": "button",
  "title": "Test Button",
  "click": {
    "actions": [
      {
        "type": "publishText",
        "text": "Button 1 was clicked"
      }
    ]
  },
  "accessibility": {
      "web": {
        "role":"heading",
        "aria-level": "3",
        "tabindex":"1",
        "aria-label":"This is aria-label for button",
        "aria-hidden":"false"
      }
  }
}

How to Control Structured Content Interactivity

While structured content forms have been sent in the conversations:

Various forms of structured content remain interactive even if they are no longer the most recent message from the agent/bot. As a result, users are able to scroll up in the conversation and continue to click on options from structured content. In many cases this can result in messages being delivered to the bot that it cannot interpret, as it is no longer expecting responses from previous structured content. This causes interruptions in the conversational flow, resulting in a poor customer experience. So you would like to have option to block action from old structured content forms.
Or you would like to lock the free-form text in the engagement window when a brand wants to force a guided flow to collect specific responses.

There are two ways to configure what specific behavior you want for each individual piece of structured content.

Configure for individual structured content message

Property Name	Description
`"customContainerSettings": { "blockTextInput": true }`	User will not be able to input text until another message arrives, forcing them to interact with the structured content.

"customSettings": { "blockSCWhenNotLastMsg": true } Structured Content will become non-interactive as soon as it is no longer the most recent message

Example

Block structured content condition on Parent Level

{
  "type": "carousel",
  "padding": 10,
  "customSettings": {
    "blockSCWhenNotLastMsg": true
  },
  "elements": [
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "SIM only plan - Block condtion on Parent Level",
          "tooltip": "SIM only plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Twelve month plan BYO mobile",
          "tooltip": "Twelve month plan BYO mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_1"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "SIM only plan"
              }
            ]
          }
        }
      ]
    },
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "Swap plan",
          "tooltip": "Swap plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Two year plan leasing a mobile",
          "tooltip": "Two year plan leasing a mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_2"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "Two year plan leasing a mobile"
              }
            ]
          }
        }
      ]
    }
  ]
}

Block structured content condition on Node Level

{
  "type": "carousel",
  "padding": 10,
  "elements": [
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "SIM only plan - Block condtion on Node Level",
          "tooltip": "SIM only plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Twelve month plan BYO mobile",
          "tooltip": "Twelve month plan BYO mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "customSettings": {
            "blockSCWhenNotLastMsg": true
          },
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_1"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "SIM only plan"
              }
            ]
          }
        }
      ]
    },
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "Swap plan",
          "tooltip": "Swap plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Two year plan leasing a mobile",
          "tooltip": "Two year plan leasing a mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_2"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "Two year plan leasing a mobile"
              }
            ]
          }
        }
      ]
    }
  ]
}

Block Text Input condition on Parent Level

{
  "type": "carousel",
  "padding": 10,
  "customContainerSettings": {
    "blockTextInput": true
  },
  "elements": [
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "SIM only plan - Block Text Input on parent level",
          "tooltip": "SIM only plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Twelve month plan BYO mobile",
          "tooltip": "Twelve month plan BYO mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_1"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "SIM only plan"
              }
            ]
          }
        }
      ]
    },
    {
      "type": "vertical",
      "elements": [
        {
          "type": "text",
          "text": "Swap plan",
          "tooltip": "Swap plan",
          "rtl": false,
          "style": {
            "bold": false,
            "italic": false,
            "color": "#000000",
            "size": "large"
          }
        },
        {
          "type": "text",
          "text": "Two year plan leasing a mobile",
          "tooltip": "Two year plan leasing a mobile",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "ANOTHER_ONE_2"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "Two year plan leasing a mobile"
              }
            ]
          }
        }
      ]
    }
  ]
}

Block Text Input & structured content condition on Parent Level

{
"type": "carousel",
"padding": 10,
"customContainerSettings": {
  "blockTextInput": true
},
"customSettings": {
  "blockSCWhenNotLastMsg": true
},
"elements": [
  {
    "type": "vertical",
    "elements": [
      {
        "type": "text",
        "text": "Block Text Input & SC condition on Parent Level",
        "tooltip": "SIM only plan",
        "rtl": false,
        "style": {
          "bold": false,
          "italic": false,
          "color": "#000000",
          "size": "large"
        }
      },
      {
        "type": "text",
        "text": "Twelve month plan BYO mobile",
        "tooltip": "Twelve month plan BYO mobile",
        "rtl": false,
        "style": {
          "bold": true,
          "italic": false,
          "color": "#000000"
        }
      },
      {
        "type": "button",
        "tooltip": "Choose a plan",
        "title": "Choose a plan",
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "ANOTHER_ONE_1"
            }
          ],
          "actions": [
            {
              "type": "publishText",
              "text": "SIM only plan"
            }
          ]
        }
      }
    ]
  },
  {
    "type": "vertical",
    "elements": [
      {
        "type": "text",
        "text": "Swap plan",
        "tooltip": "Swap plan",
        "rtl": false,
        "style": {
          "bold": false,
          "italic": false,
          "color": "#000000",
          "size": "large"
        }
      },
      {
        "type": "text",
        "text": "Two year plan leasing a mobile",
        "tooltip": "Two year plan leasing a mobile",
        "rtl": false,
        "style": {
          "bold": true,
          "italic": false,
          "color": "#000000"
        }
      },
      {
        "type": "button",
        "tooltip": "Choose a plan",
        "title": "Choose a plan",
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "ANOTHER_ONE_2"
            }
          ],
          "actions": [
            {
              "type": "publishText",
              "text": "Two year plan leasing a mobile"
            }
          ]
        }
      }
    ]
  }
]
}

Block Text Input on Parent Level & Block structured content condition on Node Level

{
"type": "carousel",
"padding": 10,
"customContainerSettings": {
  "blockTextInput": true
},
"elements": [
  {
    "type": "vertical",
    "elements": [
      {
        "type": "text",
        "text": "Block Text Input on Parent Level &  Block SC condition on Node Level",
        "tooltip": "SIM only plan",
        "rtl": false,
        "style": {
          "bold": false,
          "italic": false,
          "color": "#000000",
          "size": "large"
        }
      },
      {
        "type": "text",
        "text": "Twelve month plan BYO mobile",
        "tooltip": "Twelve month plan BYO mobile",
        "rtl": false,
        "style": {
          "bold": true,
          "italic": false,
          "color": "#000000"
        }
      },
      {
        "type": "button",
        "tooltip": "Choose a plan",
        "title": "Choose a plan",
          "customSettings": {
  "blockSCWhenNotLastMsg": true
},
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "ANOTHER_ONE_1"
            }
          ],
          "actions": [
            {
              "type": "publishText",
              "text": "SIM only plan"
            }
          ]
        }
      }
    ]
  },
  {
    "type": "vertical",
    "elements": [
      {
        "type": "text",
        "text": "Swap plan",
        "tooltip": "Swap plan",
        "rtl": false,
        "style": {
          "bold": false,
          "italic": false,
          "color": "#000000",
          "size": "large"
        }
      },
      {
        "type": "text",
        "text": "Two year plan leasing a mobile",
        "tooltip": "Two year plan leasing a mobile",
        "rtl": false,
        "style": {
          "bold": true,
          "italic": false,
          "color": "#000000"
        }
      },
      {
        "type": "button",
        "tooltip": "Choose a plan",
        "title": "Choose a plan",
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "ANOTHER_ONE_2"
            }
          ],
          "actions": [
            {
              "type": "publishText",
              "text": "Two year plan leasing a mobile"
            }
          ]
        }
      }
    ]
  }
]
}

CheckBox List Block Parent Level

{
"type": "list",
"customSettings": {
  "blockSCWhenNotLastMsg": true
},
"elements": [
  {
    "type": "text",
    "text": "The checklist"
  },
  {
    "type": "sectionList",
    "elements": [
      {
        "type": "section",
        "sectionID": "fruits",
        "elements": [
          {
            "type": "text",
            "text": "The subheader"
          },
          {
            "type": "checklist",
            "elements": [
              {
                "type": "checkbox",
                "text": "apple",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_35"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "apples"
                    }
                  ]
                }
              },
              {
                "type": "checkbox",
                "text": "banana",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_32"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "bananas"
                    }
                  ]
                }
              },
              {
                "type": "checkbox",
                "text": "avocado",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_36"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "avocados"
                    }
                  ]
                }
              }
            ]
          }
        ]
      },
      {
        "type": "section",
        "sectionID": "fruits123",
        "elements": [
          {
            "type": "text",
            "text": "The subheader2"
          },
          {
            "type": "checklist",
            "elements": [
              {
                "type": "checkbox",
                "text": "apple1",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_35"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "apples"
                    }
                  ]
                }
              },
              {
                "type": "checkbox",
                "text": "banana2",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_32"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "bananas"
                    }
                  ]
                }
              },
              {
                "type": "checkbox",
                "text": "avocado3",
                "borderLine": true,
                "borderColor": "#000000",
                "click": {
                  "metadata": [
                    {
                      "type": "ExternalId",
                      "id": "ANOTHER_ONE_36"
                    }
                  ],
                  "actions": [
                    {
                      "type": "checked",
                      "publishText": "avocados"
                    }
                  ]
                }
              }
            ]
          }
        ]
      }
    ]
  },
  {
    "type": "buttonList",
    "elements": [
      {
        "type": "submitButton",
        "title": "submit",
        "disabled": false,
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "submissionID"
            }
          ],
          "actions": [
            {
              "type": "submitAsText",
              "submit": true
            }
          ]
        }
      },
      {
        "type": "button",
        "title": "Back",
        "click": {
          "metadata": [
            {
              "type": "ExternalId",
              "id": "ANOTHER_ONE_20"
            }
          ],
          "actions": [
            {
              "type": "publishText",
              "text": "Back"
            }
          ]
        }
      }
    ]
  }
]
}

Configure for account level

Please reach out to your account manager to configure on Site Setting. These two flags will be applied to all structured content messages.

Name	Description
messaging.web.blockTextInputDefault	User will not be able to input text until another message arrives, forcing them to interact with the structured content. Default value: `false`
messaging.web.blockSCWhenNotLastMsgDefault	Structured Content will become non-interactive as soon as it is no longer the most recent message. Default value: `false`

Notes

If the attribute at the individual structured content schema is present then it will be considered as high priority and the Site Setting will be ignored.
If the attribute at the individual structured content schema is NOT present then the Site Setting will be honored.
Not present means that the attribute should not be in the structured content JSON payload. If the attribute is present with false value, then the attribute in the SC JSON payload should be honored.

Additional Structured Content JSON examples

Single/Multi-Select Card Carousels

Side Arrows can be modified using the style attribute

{
  "type": "carousel",
  "padding": 10,
  "style": {
    "fill": "white"
  },
  "elements": [
    {
      "type": "vertical",
      "elements": [
        {
          "type": "image",
          "url": "https://cdn.zeplin.io/5aa650d695bfea607a2c9351/assets/7289E842-10A3-40C3-B4A7-F1856B574CD0.png",
          "tooltip": "SIM only plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "11114444"
              }
            ]
          }
        },
        {
          "type": "text",
          "text": "Small plan 2 GB data ",
          "tooltip": "Small plan",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000",
            "background-color": "#FFFFFF",
            "background-color-hover": "#EB455F",
            "color-hover": "#FCFFE7",
            "border-color-hover": "#F5FFC6",
            "font-family": "sans-serif"
          }
        },
        {
          "type": "text",
          "text": "500$ national talk",
          "tooltip": "500$",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "text",
          "text": "49$ per month",
          "tooltip": "49$",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": true,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "nav",
          "title": "Navigate to Alice",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "12345678"
              }
            ],
            "actions": [
              {
                "type": "publishText",
                "text": "my text"
              },
              {
                "type": "navigate",
                "name": "Navigate to store via image",
                "lo": 34.88248,
                "la": 32.19777
              }
            ]
          }
        }
      ]
    },
    {
      "type": "vertical",
      "elements": [
        {
          "type": "image",
          "url": "https://cdn.zeplin.io/5aa650d695bfea607a2c9351/assets/D767223B-CC51-431A-A26E-B54C39EA7846.png",
          "tooltip": "Large plan",
          "click": {
            "metadata": [
              {
                "type": "ExternalId",
                "id": "11114444"
              }
            ]
          }
        },
        {
          "type": "text",
          "text": "unlimited international talk",
          "tooltip": "unlimited international",
          "rtl": false,
          "style": {
            "bold": true,
            "italic": false,
            "color": "#000000"
          }
        },
        {
          "type": "button",
          "tooltip": "Choose a plan",
          "title": "Choose a plan",
          "click": {
            "actions": [
              {
                "type": "link",
                "name": "Add to cart",
                "uri": "https://cdn.zeplin.io/5aa650d695bfea607a2c9351/assets/45246060-E3A7-4477-A26B-F6D74A28D49E.png"
              }
            ]
          }
        }
      ]
    }
  ]
}

Accordion-Style Structured Content with Multiselect

{
  "type": "vertical",
  "border": "borderLess",
  "elements": [
    {
      "type": "accordionSelect",
      "padding": 10,
      "selectMode": {
        "name": "test-accordion-multi-select"
      },
      "titles": [
        {
          "name": "First accordion tab",
          "additional": "Additional info"
        },
        {
          "name": "Second accordion tab",
          "additional": "$0.01"
        },
        {
          "name": "Third accordion tab",
          "additional": "Limited time offer"
        }
      ],
      "elements": [
        {
          "type": "vertical",
          "metadata": [
            {
              "type": "ExternalCardId",
              "id": "ANOTHER_ONE_1"
            }
          ],
          "border": "borderLess",
          "elements": [
            {
              "type": "text",
              "text": "Twelve month plan BYO mobile",
              "tooltip": "Twelve month plan BYO mobile",
              "rtl": false
            }
          ]
        },
        {
          "type": "vertical",
          "metadata": [
            {
              "type": "ExternalCardId",
              "id": "ANOTHER_ONE_2"
            }
          ],
          "border": "borderLess",
          "elements": [
            {
              "type": "text",
              "text": "Two year plan leasing a mobile",
              "tooltip": "Two year plan leasing a mobile",
              "rtl": false
            }
          ]
        },
        {
          "type": "vertical",
          "metadata": [
            {
              "type": "ExternalCardId",
              "id": "ANOTHER_ONE_3"
            }
          ],
          "border": "borderLess",
          "elements": [
            {
              "type": "text",
              "text": "Two year plan with a mobile",
              "tooltip": "Two year plan with a mobile",
              "rtl": false
            }
          ]
        }
      ]
    },
    {
      "type": "button",
      "title": "Submit selected",
      "ref": {
        "type": "accordionSelect",
        "name": "test-accordion-multi-select"
      },
      "click": {
        "metadata": [
          {
            "type": "ExternalId",
            "id": "ANOTHER_ONE_3"
          }
        ],
        "actions": [
          {
            "type": "publishText",
            "text": "Mobiles on a plan"
          }
        ]
      }
    }
  ]
}

Scrollable Text Fields within Structured Content

{
  "type": "vertical",
  "scroll": "enable",
  "style": {
    "size": "medium"
  },
  "elements": [
    {
      "type": "text",
      "text": "Text content",
      "tooltip": "text tooltip",
      "style": {
        "bold": true,
        "size": "large"
      },
      "accessibility": {
        "web": {
          "aria-label": "text label product"
        }
      }
    },
    {
      "type": "button",
      "class": "button",
      "title": "Add to cart",
      "tooltip": "Add to cart",
      "style": {
        "background-color": "#0363AD",
        "color": "#fff",
        "size": "medium",
        "bold": true
      },
      "click": {
        "actions": [
          {
            "type": "link",
            "name": "Buy",
            "uri": "https://example.com"
          }
        ]
      }
    }
  ]
}

Tabs within Structured Content

{
  "type": "vertical",
  "elements": [
    {
      "type": "tabs",
      "elements": [
        {
          "type": "vertical",
          "tag": "Carousel",
          "border": "borderLess",
          "elements": [
            {
              "type": "carousel",
              "padding": 10,
              "elements": [
                {
                  "type": "vertical",
                  "elements": [
                    {
                      "type": "text",
                      "text": "a",
                      "rtl": false,
                      "style": {
                        "bold": false,
                        "italic": false,
                        "color": "#000000",
                        "size": "large"
                      }
                    },
                    {
                      "type": "text",
                      "text": "Twelve month plan BYO mobile",
                      "tooltip": "Twelve month plan BYO mobile",
                      "rtl": false,
                      "style": {
                        "bold": true,
                        "italic": false,
                        "color": "#000000"
                      }
                    },
                    {
                      "type": "button",
                      "tooltip": "Choose a plan",
                      "title": "Choose a plan",
                      "click": {
                        "metadata": [
                          {
                            "type": "ExternalId",
                            "id": "ANOTHER_ONE_1"
                          }
                        ],
                        "actions": [
                          {
                            "type": "publishText",
                            "text": "SIM only plan"
                          }
                        ]
                      }
                    }
                  ]
                },
                {
                  "type": "vertical",
                  "elements": [
                    {
                      "type": "text",
                      "text": "b",
                      "tooltip": "Swap plan",
                      "rtl": false,
                      "style": {
                        "bold": false,
                        "italic": false,
                        "color": "#000000",
                        "size": "large"
                      }
                    },
                    {
                      "type": "text",
                      "text": "Two year plan leasing a mobile",
                      "tooltip": "Two year plan leasing a mobile",
                      "rtl": false,
                      "style": {
                        "bold": true,
                        "italic": false,
                        "color": "#000000"
                      }
                    },
                    {
                      "type": "button",
                      "tooltip": "Choose a plan",
                      "title": "Choose a plan",
                      "click": {
                        "metadata": [
                          {
                            "type": "ExternalId",
                            "id": "ANOTHER_ONE_2"
                          }
                        ],
                        "actions": [
                          {
                            "type": "publishText",
                            "text": "Two year plan leasing a mobile"
                          }
                        ]
                      }
                    }
                  ]
                }
              ]
            }
          ]
        },
        {
          "type": "vertical",
          "tag": "Card",
          "border": "borderLess",
          "elements": [
            {
              "type": "vertical",
              "elements": [
                {
                  "type": "text",
                  "text": "product name (Title)",
                  "tooltip": "text tooltip",
                  "style": {
                    "bold": true,
                    "size": "large"
                  },
                  "accessibility": {
                    "web": {
                      "aria-label": "text label product"
                    }
                  }
                },
                {
                  "type": "text",
                  "text": "product name (Title)",
                  "tooltip": "text tooltip"
                },
                {
                  "type": "button",
                  "tooltip": "button tooltip",
                  "title": "Add to cart",
                  "click": {
                    "actions": [
                      {
                        "type": "link",
                        "name": "Add to cart",
                        "uri": "https://example.com"
                      }
                    ]
                  }
                },
                {
                  "type": "horizontal",
                  "elements": [
                    {
                      "type": "button",
                      "title": "Buy",
                      "tooltip": "Buy this broduct",
                      "click": {
                        "actions": [
                          {
                            "type": "link",
                            "name": "Buy",
                            "uri": "https://example.com"
                          }
                        ]
                      }
                    },
                    {
                      "type": "button",
                      "title": "Find similar",
                      "tooltip": "store is the thing",
                      "click": {
                        "actions": [
                          {
                            "type": "link",
                            "name": "Buy",
                            "uri": "https://search.com"
                          }
                        ]
                      }
                    }
                  ]
                },
                {
                  "type": "button",
                  "tooltip": "button tooltip",
                  "title": "Publish text",
                  "click": {
                    "actions": [
                      {
                        "type": "publishText",
                        "text": "my text"
                      }
                    ]
                  }
                },
                {
                  "type": "map",
                  "la": 64.128597,
                  "lo": -21.89611,
                  "tooltip": "map tooltip"
                },
                {
                  "type": "button",
                  "tooltip": "button tooltip",
                  "title": "Navigate",
                  "click": {
                    "actions": [
                      {
                        "type": "publishText",
                        "text": "my text"
                      },
                      {
                        "type": "navigate",
                        "name": "Navigate to store via image",
                        "lo": 23423423,
                        "la": 2423423423
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      ]
    }
  ]
}

Faster Better answers through AI

Introduction

What is Structured Content

How to Send Structured Content to the Conversation

Human Agent

Bot Agent

Templates

Example

Properties

Example

Basic Elements

Button

Properties

Example

Image

Properties

Example

Map

Properties

Example

Text

Properties

Example

Element Click Operations

Example

Actions

Navigate

Properties

Example

Link

Properties

Example

Publish Text

Properties

Example

Metadata

Element Styling

Properties

Example

Element Accessibility Attributes

Properties

Example

How to Control Structured Content Interactivity

Configure for individual structured content message

Example

Configure for account level

Notes

Additional Structured Content JSON examples

Single/Multi-Select Card Carousels

Side Arrows can be modified using the style attribute

Accordion-Style Structured Content with Multiselect

Scrollable Text Fields within Structured Content

Tabs within Structured Content