Displaying Content Cards

Modified on Sun, 2 Mar at 6:39 PM

Overview

The standard user interface through DDNA Studio provides the opportunity to make conversations multi-modal through supplemental content and displays known as ‘Content Blocks’. By sending additional data from your conversation platform, you are able to display richer content at relevant points of the conversation along with the spoken audio stream.

Tip: We recommend you use the Content Cards Skill to simplify this process for External Links, Video, and Markdown cards.

Prerequisites and Known Limitations

Note: This guide only applies to the Default UI and the Widget through the Digital DNA Studio. If you are building your own custom UI, this guide does not apply and you should consult Building Content Cards .

Using Content Blocks

To enable the display of rich content, our standard user interface offers the following content options: Images, Lists, Links, Markdown, and Video.

Info: It is important to associate each card with a unique Id, this is used in content awareness (developer docs), so the Digital Person can glance at it.

Note: It is recommended to use the custom payload option in Dialogflow ES and CX to define content cards.

Single Images DEFAULT UI Widget

Displays a single image, either from a URL or encoded string.

Info: The general recommendation would be to use images of 960 x 960 pixels at 72-144px DPI and/or a file size of 100kb or less.

Payload

The payload must be in a valid JSON format.

{

  "type": "image",

  "id": "image",

  "data": {

    "url": "https://placekitten.com/500/500",

    "alt": "This is a cat"

  }

}

Properties

Available within the “data” attribute of the payload.

URL
required

A url or base64 encoded string representing an image.

URL

When using a url, the url must be accessible by the UI. For example, if the UI is accessed via https, then image URLs must also be accessed using https.

Use the prefix // to access the image using the same protocol at the host UI. The hosted image must support both http and https, if this approach is to be used.
e.g. "url": "//www.soulmachines.com/wp-content/uploads/sm-logo-retina.png"

The url must have a prefix.
e.g. "url": "soulmachines.com/wp-content/uploads/sm-logo-retina.png" will not work.

Base64 Encoded String

For base64 encoding see MDN: Data URLs or StackOverflow: How to display Base64 images in HTML

alt Text to be used for screen readers or when the image is not available. For more information see MDN: The Image Embed Element

Example

Example of an Image content block

Multiple Image Sequence DEFAULT UI Widget

You may display different images, one at a time by defining the individual data for each image in the NLP and using multiple @showCards() commands in the Conversation Response.

Example:

public-mydog

{
  "type": "image",

  "id": "image-dog",

  "data": {

    "url": "https://www.yoururl.com/dog.png",

    "alt": "This is a dog"
  }
}

public-mycat

{
  "type": "image",

  "id": "image-cat",

  "data": {

    "url": "https://www.yoururl.com/cat.png",

    "alt": "This is a cat!"
  }
}

Conversation Response

Here is a picture of a cat @showCards(mycat) #PauseOne and here is a picture @hidecards() of a @showcards(mydog) dog.

Options DEFAULT UI Widget

Displays a collection of prompts/buttons for the user to guide them through a conversation. When an option is clicked, its value is sent through to the NLP platform in the same way as a spoken command.

Payload

The payload must be in a valid JSON format.

{
  "type": "options",
  "id": "options",
  "data": {
    "options": [
      { "label": "First Option", "value": "Tell me about the option one"},
      { "label": "Second Option", "value": "Tell me about the option two"},
      { "label": "Third Option", "value": "Tell me about the option three"}
    ]
  }
}

Properties

Available within the “data” attribute of the payload.

options
required

An array of objects where each object defines the option.

The property “label” is used to display text within the button / option in the UI
The property “value” may also be used to match a possible spoken response by the user. The list option could then be clicked as a form of selecting it (in addition to speaking the list option), e.g. the “value” property is sent to the NLP for intent matching.

Example

Example of a List content block

External Links DEFAULT UI Widget

Displays a hyperlink in the form of a clickable button, when clicked, opens the link in a new tab of the browser.

Note: The UI is responsive—if the screen size is smaller than a tablet, the image is hidden.

Payload

The payload must be in a valid JSON format.

{

  "type": "externalLink",

  "id": "externalLink",

  "data": {

    "url": "https://www.soulmachines.com",

    "title": "Soul Machines",

    "imageUrl": "https://www.soulmachines.com/wp-content/uploads/cropped-sm-favicon-180x180.png",

    "description":"Soul Machines is the leader in astonishing AGI"

  }

}

Properties

Available within the “data” attribute of the payload.

url required	A url string representing an external link; E.g. “https://www.soulmachines.com”
imageUrl required	A url for an image to be displayed as the graphical support to accompany the external link. E.g. “https://domainname.com.au/picture.jpg”
Title required	Text that is displayed above the external link and below the image.
description optional	Text that is displayed below the Title.

Example

Example of External Link Content Block

Internal Links Widget

Displays a hyperlink in the form of a clickable image, when clicked, opens the link in the same tab of the browser.

Note: The UI is responsive—if the screen size is smaller than a tablet, the image is hidden

Payload

The payload must be in a valid JSON format.

{
  "type": "internal",

  "id": "internalLink",

  "data": {

    "url": "https://www.soulmachines.com",

    "title": "Soul Machines",

    "imageUrl": "https://www.soulmachines.com/wp-content/uploads/cropped-sm-favicon-180x180.png",

    "description":"Soul Machines is the leader in astonishing AGI"
  }
}

Properties

Available within the “data” attribute of the payload.

url required	A url string representing an external link; E.g. “https://www.soulmachines.com/resources/ ”
imageUrl required	A url for an image to be displayed as the graphical support to accompany the internal link. E.g. “https://domainname.com.au/picture.jpg%E2%80%9D
Title required	Text that is displayed above the internal link and below the image.
description optional	Text that is displayed below the Title.

Example

Example of Internal Link Content Block

Markdown DEFAULT UI Widget

Displays styled markdown compatible content.

Payload

The payload must be a valid JSON format, including the value of the “text” attribute, which must be escaped in order to be valid.

{

  "type": "markdown",

  "id": "markdown-content",

  "data": {

    "text": "## An Interesting List\r\n 1. Most interesting\r\n 2. Less interesting\r\n 3. Least Interesting"

  }

}

Properties

Available within the “data” attribute of the payload.

text
required

Static text to be displayed and not spoken by Digital Person. Markdown markup language can be used to add formatting to this text.

For example:
“This is **Bold **”.

This will display as “This is Bold”

The value of the text attribute must be valid JSON and must be correctly escaped (see below).

Example

Example of a Markdown content block

Video DEFAULT UI

Displays a video player for a specific YouTube video, enabling the end-user to watch a video in line with the experience with the Digital Person.

Payload

The payload must be in a valid JSON format.

{

  "type": "video",

  "id": "youtubeVideo",

  "data": {

    "videoId":"vxmthHfkoaw",

    "autoclose":"true"
  }
}

Properties

Available within the “data” attribute of the payload.

videoId
required The YouTube videoId for the video you wish to embed.
You may find your videoId on the end of the YouTube video URL i.e.
https://www.youtube.com/watch?v=vxmthHfkoaw

autoplay: Boolean
optional

Configure the video card to auto-play at the time it’s rendered by the showcardsevent.

When the autoplay attribute is not included in the payload, the video card will not play until the user clicks the “play” button, on all platforms.
When autoplay is included in the payload and set to true/false, the video will pop up to full screen and begin playing as soon as showcards is triggered for the card.

Note: On most mobile devices, autoplay of videos is not supported. A video with autoplay:true

automatically pop ups to cover the screen, but the user needs to click the play button to begin the video.

autoclose: Boolean (default false)
optional

Configure the video card to close automatically when the video ends.

When autoplay is set to false for a video card, the video card does not close until the user clicks the “I'm done watching” button.

When autoclose is set to true for a video card, the video player closes at the end of the video and enables you to immediately continue the conversation.

After Playback

If the autoclose has not been configured, the user can click the “I'm done watching” button at any time to close the video player.
At this point the text “I'm done watching” is sent to your NLP engine so you may continue the conversation—you must create an intent to match “I'm done watching” and respond accordingly.

Example

Example of a Video content block

Implementing into your NLP

See Building Content Cards for NLP-specific examples and how to use Content Cards in a custom UI.

IBM Watson (classic) sample

This sample contains a set of Nodes that demonstrates how to display each of the supported content types.

Download the sample .json file
Import the file to your Watson skill.

https://drive.google.com/file/d/1Riu6bJY7DcWskepC7vj6f8oikKwkbUlI/view?usp=sharing

Google Dialogflow ES sample

This sample contains a set of Intents that demonstrates how to display each of the supported content types.

Download the sample .zip file
Import the file to your Dialogflow agent.

https://drive.google.com/file/d/15uXWbRHFMrwZ2_MPVmRsIawtYpP6H_ox/view?usp=sharing

Displaying Content Cards

Overview

Prerequisites and Known Limitations

Using Content Blocks

Single Images DEFAULT UI Widget

Payload

Properties

Example

Multiple Image Sequence DEFAULT UI Widget

public-mydog

public-mycat

Conversation Response

Options DEFAULT UI Widget

Payload

Properties

Example

External Links DEFAULT UI Widget

Payload

Properties

Example

Internal Links Widget

Payload

Properties

Example

Markdown DEFAULT UI Widget

Payload

Properties

See Also

Example

Video DEFAULT UI

Payload

Properties

After Playback

Example

Implementing into your NLP

IBM Watson (classic) sample

Google Dialogflow ES sample