Defining rich media widgets

This topic explains how to configure question and answer nodes with interactive elements, to generate rich media widgets such as quick reply buttons, forms, formatted links, carousels, and so on, for the chat interface of your virtual assistant.

Prerequisites

Your NDEP system must have Chat Interface Version 2, and must have been configured with JSON definitions for the desired rich media elements (refer to the NDEP documentation).

Rich media support by channel

For certain channels, virtual assistants designed in Mix can support quick reply buttons and formatted links (internal hyperlinks) thanks to NDEP’s predefined rich media widget conversion templates. They can also render freeform rich media widgets from JSON definitions that comply with Nuance’s Rich Media Standard.

These channels are compatible with NDEP’s predefined rich media widget conversion templates:

  • Web
  • App
  • GBM
  • WhatsApp
  • Viber
  • Telegram
  • Line
  • Instagram

Configuring interactive elements for rich media in Mix.dialog

In the question and answer node that is meant to elicit a response via rich media interaction, use the interactivity properties Type and Class or CSS.

In Type (required):

  • For quick reply buttons, enter quickReply
  • For formatted links, enter formattedLink
  • For freeform media, enter freeform

In Class or CSS (optional), for quick reply buttons, enter the JSON definition of any desired customization.

See Define interactive elements, in the Mix.dialog documentation, for more information.

Quick reply button configuration example

This example shows how to configure interactive elements for a question and answer node, to be rendered as quick reply buttons in the chat interface.

  1. Navigate to the Interactivity properties.

  2. Set Type to quickReply.

  3. To customize the look and feel of the quick reply buttons, enter the desired JSON payload in the Class or CSS field. For example:

    {
    "widgetView": "inline",
    "widgetAction": "optional",
    "showMessageText": true,
    "context": {
        "textStyle": "bold",
        "selectedTextColor": "#FFFFFF",
        "selectedColor": "#D71E28",
        "selectedBorderColor": "#D71E28"
    }
}

  4. For each value of the entity to collect, turn on the corresponding switch, and specify a label or the URL of the desired image.

This scenario shows how to configure initial and reentry messages for a question and answer node, to embed the possible answers as formatted links (internal hyperlinks) directly in the message body.

Let’s say you’re configuring a question and answer node that is meant to ask Do you want to pay with Visa or Mastercard?, where Visa and Mastercard represent values of the payee entity. You want the end user to be able to select the desired payee directly on the message (as opposed to selecting a button under the message, for example). For this to be possible, you must configure the system question—initial and reentry messages (if any)—with special markup around the possible answers, and define interactivity properties for these answers.

  1. Navigate to the Initial message properties for your question and answer node.
  2. Enter the desired initial message—for example, Do you want to pay with Visa or Mastercard?
  3. To turn the parts Visa and Mastercard into formatted links within the message, use this syntax {entityName=entityValue}, where entityName is the name of the entity being collected, and entityValue is the value that will be recognized when a user selects this part of the message—in this scenario:
    Do you want to pay with {payee=visa} or with {payee=discover}?
    Make sure the entity name and values in your messages have exact same spelling as what appears in the Interactivity properties of the question and answer node.
  4. Proceed in the same fashion for the reentry messages, if any.
  5. Navigate to the Interactivity properties.
  6. Set Type to formattedLink.
  7. For each value of the entity to collect, turn on the corresponding switch, and enter a label.
    The labels will be used for the text of the links in the chat interface.

This scenario shows how to configure initial and reentry messages with explicit formatting, for example to generate response feedback in addition to including the possible answers as formatted links directly in the message body.

  1. Navigate to the Initial message properties for your question and answer node.
  2. Enter the desired initial message—for example, Do you want to pay with Visa or Mastercard?
  3. Turn the parts Visa and Mastercard into hyperlinks—for example, like this:
    Do you want to pay with <a href="#" data-nuance-message-text="Visa" data-nuance-message-data="{\"nvaaType\":\"formattedLink\",\"selectedItemId\":\"payee\",\"selectedItemValue\":\"visa\"}">Visa</a> or with <a href="#" data-nuance-message-text="Mastercard" data-nuance-message-data="{\"nvaaType\":\"formattedLink\",\"selectedItemId\":\"payee\",\"selectedItemValue\":\"mastercard\"}">Mastercard</a>?
    See Hyperlinks for more information on the attributes data-nuance-message-text and data-nuance-message-data.
  4. Proceed in the same fashion for the reentry messages, if any.
  5. Navigate to the Interactivity properties.
  6. Leave the Type field empty (the hyperlink definitions in your messages already specify formattedLink).
  7. For each value of the entity to collect, turn on the corresponding switch, and enter a label.
    (In this case, the label won’t be used but Mix.dialog requires a label or image URL when you configure interactivity for a value.)

Freeform configuration example

This scenario shows how to configure a question and answer node, to generate a freeform rich media widget in the chat interface—in this case, a field where the user must enter their account number. This widget supports input validation (based on the criteria specified in its validation structure) and returns any variables specified in its displayToAgent structure—in this case, the variable named personalAccountNumber.

  JSON definition example for freeform rich media  

In Mix.dialog, you must have defined a variable of type string to hold the desired JSON definition. The variable name must be nvaaMessageData (see Reserved variables for NDEP). You can either use this variable in a data access node, as a Get parameter, to get the JSON definition from a backend, or set it directly in the Start node of your dialog design.

You must also define variables of type string for any variables specified in the displayToAgent structure of your JSON definition—in this case, personalAccountNumber.

Once you have defined all the required variables, proceed as follows:

  1. Navigate to the Interactivity properties.
  2. Set Type to freeform.
  3. Switch to the Advanced properties and navigate to Send data.
  4. Add your nvaaMessageData variable as a Send parameter.
  5. In the System actions properties, add the desired actions and conditions.
    For example, set a condition to verify if the returned personalAccountNumber is not null, before assigning its value to the entity in focus at this node and setting its .isCompleted attribute to true before returning to the question router node that handles this entity. If the widget failed to return the account number, you might show a message before returning to the question router node. See Entity lifecycle considerations in the Mix.dialog documentation for more information.