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.
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
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 for screen readers |
tabindex | Describes the tab navigation order of elements |
aria-label | Describes a string value that labels an element |
aria-level | Used together with role=heading to specify the heading level of the element |
aria-describedby | Reference longer content to provide description with relevant id |
aria-labelledby | Reference other elements to define accessible name |
aria-hidden | Hide/show the element from assistive technology |
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"
}
}
}
For a list of Rich Messaging capabilities for each channel, browse or search the table on the Knowledge Center.