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.

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

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:

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

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

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

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

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:

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

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

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

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

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

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.