Widget properties

The set of properties in this table defines both:

  • how a widget is displayed in a chat transcript

  • how a widget behaves when a user interacts with it

Property Description Supported values Required
displayInRestore

Indicates whether to restore rich mean when reloading the chat window, which usually happens when the user navigates to a new page. In most cases, accept the default value.

  • true—Default. Rich Media is displayed when the chat window is reloaded.

  • false—Rich Media is not displayed when the chat window is reloaded.

no
historicHidden

Indicates whether to display the widget from previous conversations.

Note: This property is relevant only to asynchronous conversations.

  • true—Widget from previous conversations is not displayed . This is useful for items related to a previous conversation, such as a rating or a login UI.

  • false—Default. Widget is displayed for previous conversations.

no
historicLockView

Indicates whether to disable widget controls from previous conversations.

Note: This property is relevant only to asynchronous conversations.

  • true—Default. When the user views widgets from previous conversations, form controls are disabled. This is useful for most use cases

  • false—Form controls are enabled for widgets from previous conversations. This may be useful for navigation-based quick reply buttons, or widgets that users may want to use again to launch out of chat window actions, such as opening deep links.

no
initialView The node ID of the node to display first.

For more information, see id in Define nodes.

required only if widget contains multiple nodes
lockView

Indicates whether to disable the widget controls after the user completes the interaction.

  • true—Default. After the user completes the interaction with the widget, all controls are disabled. This is useful for forms or any other interactive media where you want to prevent the user from returning later in the conversation and submitting new information.

  • false—Controls remain enabled after the user interacts with the widget. This is useful for widgets where you expect a user to return, such as a list of quick reply buttons that prompt the user with different topics to explore.

no
pagination

Displays a bar at the top of the widget to show the page where the user is located. The position of the bar is based on the position order of the node in the list of nodes. This property is an object containing two key/value pairs:

  • “background”: “COLOR

  • “style”: “STYLE

Note: This property is relevant only to widgets with multiple nodes or pages.

  • COLOR is a hex color code.

  • STYLE is one of the following:

    • step–The bar moves to steps across the top of the widget as the user moves through thenodes.

    • extend–The bar extends from left to right as the user moves through the nodes.

no
showMessageText

Indicates whether to display any accompanying messageText from the agent.

Note: Messages sent with this flag do not display an agent avatar.

  • true—Displays any accompanying messageText from the agent. This is recommended if the agent message prompts an action from the user. For example, “Did this answer your question?” for a widget that displays “Yes” or “No”.

  • false—Default. Does not display any accompanying messageText from the agent. If the widgetView property, described below, is set to bubble, then use this value. This is useful when no prompt is needed, or when the prompt is already included in your widget. Use this in a form that includes detailed instructions or a call to action.

no
showMessageTextInRestore

Indicates whether to display any accompanying messageText from the agent when the chat window is reloaded. This value is used when the chat window is reloaded, typically because the user has navigated to a new page. Except in rare circumstances, accept the default value.

Defaults to the value of showMessageText, described above.

  • true—Message text is displayed when the chat window is reloaded.

  • false—Message text is not displayed when the chat window is reloaded.

no
type Rich-media type. The type for each widget is listed in the corresponding topic in the Widget reference. yes
widgetAction

Indicates whether the user can continue to type and send messages without interacting with the widget.

  • optional—The user can continue to type and send messages without interacting with the widget. This is recommended for all non-interactive widgets and almost all interactive use cases.

  • required—The user must interact with the widget before sending additional messages and continuing the conversation. Use this sparingly and only where you must ignore text responses, such as when speaking with a Virtual Assistant whose conversational design requires a response to the question asked through the Rich Media widget.

yes
widgetType

Facilitates CSS customization. This string is added as a class to your widget inside the “nuance-widget-container” element when it is rendered in HTML.

For example, if a sales flow has a different visual design than a support flow, specifying the widgetType as sales or support enables you to target each with CSS selectors.

This property accepts any text string. It defaults to null.

no
widgetView

Indicates whether widget is displayed inside or outside the agent’s speech bubble.

  • inline—Widget is displayed outside the agent’s speech bubble, inside the transcript area. This is usually recommended for interactive widgets and for most static use cases.

  • bubble—Widget is displayed inside the agent’s speech bubble. This ignores the showMessageText property, described above, and it replaces everything inside the agent bubble.
    Tip: Use this to send a multimedia message that combines multiple elements such as text, tables, columns, images, and video.

yes