Configuring a Show Step

This Conversational A.I. How-To article provides information on configuring Show Steps within an Intent design using the various content types.

Overview

Show Steps allow creation of the following content types. This article covers configuration of each type of step.

• Card
  • Includes a variety of optional components including title, sub-title, text, footer, and/or image. Actual presentation will depend on the channel.
• Custom HTML
  • Custom HTML.
• Dynamic Credential
  • Prompts the user to carry out an OAuth2 or SAML authorization with an external service identified by a specified Dynamic Credential. One a user is authenticated with the specified external service, you can use a connector to connect to that service on behalf of the user.
• Form
  • Presents a form of your choosing that the user should fill out and submit. The bot will wait for the user to submit the form (or cancel it) before continuing.
• Image
  • Presents an image. You can select an image from the image library or provide a URL.
• Link
  • A hyperlink to a web resource. By default, the link will be presented directly to the bot user and if the user clicks on the link it will launch in a new browser window. A variety of options are available, however, to control exactly how the link is handles. Use this type to present links to web pages, images, videos, and files.
• Text
  • Plain text which may contain limited markdown.
• Text with Actions
  • Plain text, which may contain limited markdown, followed by one or more action buttons or links. The user can click on the buttons or links to submit further requests to the bot or launch external web pages.

Content and Dynamic Tools

When entering a field within one of the below Content Types, the following tools will appear. Below is a description of each tool.

Card

Includes a variety of optional components including title, sub-title, text, footer, and/or image. Actual presentation will depend on the channel.

1. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.
2. Title
   • Can support raw text and dynamic content, such as properties established within the intent or the conversation and expressions.
3. Subtitle
   • Can support raw text and dynamic content, such as properties established within the intent or the conversation and expressions.
4. Text
   • Can support raw text and dynamic content, such as properties established within the intent or the conversation and expressions.
5. Footer
   • Can support raw text and dynamic content, such as properties established within the intent or the conversation and expressions.
6. Image
   • Allows selection of previously selected images from either a personal or organizational library. 
   • Allows upload of new images with the supported file types of:
     • PNG
     • JPG
     • GIF
     • SVG

Custom HTML

Custom HTML.

1. Content Source
   • Setting determines what type of source content will be used for the custom HTML module.
     • Editor
       • Provides a WYSIWYG editor and a Raw HTML editor.
     • Expression
       • Allows a combination of formatted text and expressions
2. HTML
   • Content can be added into the text area and formatted accordingly using the built in tools. To access additional formatting and content tools, select the three vertical dots along the right hand side of the HTML content area.
3. Raw HTML
   • Allows for editing of the HTML source code of a Show step. By default, the raw HTML is sanitized to protect against any dangerous HTML code.
4. Sanitize HTML
   • ​​​​​​​By default, the system "sanitizes" your HTML by removing potentially dangerous content such as script tags that will execute code inside the bot. Uncheck this box to allow such content.​​​​​​​

Dynamic Credential

Prompts the user to carry out an OAuth2 or SAML authorization with an external service identified by a specified Dynamic Credential. One a user is authenticated with the specified external service, you can use a connector to connect to that service on behalf of the user.

1. Name
   • A name for the step that can be used to refer to it (and, therefore, the value of the entity) later in the intent flow.
2. Dynamic Credential
   • Choose an Authorization to obtain from the TD Bot user. Authorizations can be created from the application navigation area on the left. Once a user authorizes with an external system, a dynamic credential will be created for that system. This dynamic credential can then be used just like any other credential - to connect to an external system on behalf of the TD Bot user, for example.
3. Bot Asks
   • What the bot should ask the user. You can provide multiple versions and the bot will choose one at random. This can be used to make the bot seem more conversational or human.
     • Note that all text elements may include the following markdown formatting:
       • Bold: **text**
       • Italics: *text*
       • Link: [text](link)
       • Button: [[text]](link)
     • If the content type is Link, Form, Image, or Dynamic Credential, the following behavior is observed:
       • If no phrases are provided here, the user will be presented with the link directly (the URL will be visible).
       • If a phrase is provided here and it does not contain the macro text {{link}} or {{formlink}}, the user will be presented with the phrase and the entire phrase will link out to the provided URL or form.
       • If a phrase is provided here and it contains the macro text {{link}}, {{formlink}}, or {{host}}, the macro text will be replaced with the full URL or host as appropriate and the user will be presented with the resulting phrase. Use this in combination with the [text](link) markdown syntax to embed the link/form in the phrase, form example 'Please click [here]({{link}})'.
4. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.

Form

Link to form from chat conversation

Example form in new window

Presents a form of your choosing that the user should fill out and submit. The bot will wait for the user to submit the form (or cancel it) before continuing. Prior to creating a Form Show Step, navigate to the Forms sidebar and design a new form if necessary.

1. Form
   • Presents the selected form to the user. The bot will wait for the user to fill in and submit the form. The user can also choose to cancel the form. If the user cancels the form, the WasCancelled property of the form step's output data will be set to true.
2. Name
   • A name for the step that can be used to refer to it (and, therefore, the data provided on the form) later in the intent flow.
3. Bot Says
   • What the bot should say to the user. You can provide multiple versions and the bot will choose one at random. This can be used to make the bot seem more conversational or human.
     • Note that all text elements may include the following markdown formatting:
       • Bold: **text**
       • Italics: *text*
       • Link: [text](link)
       • Button: [[text]](link)
     • If the content type is Link, Form, Image, or Dynamic Credential, the following behavior is observed:
       • If no phrases are provided here, the user will be presented with the link directly (the URL will be visible).
       • If a phrase is provided here and it does not contain the macro text {{link}} or {{formlink}}, the user will be presented with the phrase and the entire phrase will link out to the provided URL or form.
       • If a phrase is provided here and it contains the macro text {{link}}, {{formlink}}, or {{host}}, the macro text will be replaced with the full URL or host as appropriate and the user will be presented with the resulting phrase. Use this in combination with the [text](link) markdown syntax to embed the link/form in the phrase, form example 'Please click [here]({{link}})'.
4. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.

Image

Presents an image. You can select an image from the image library or provide a URL.

1. Name
   • A name for the step that can be used to refer to it (and, therefore, the value of the entity) later in the intent flow.
2. Image
   1. Allows selection of previously selected images from either a personal or organizational library. 
   2. Allows upload of new images with the supported file types of:
      • PNG
      • ​​​​​​​JPG
      • ​​​​​​​GIF
      • ​​​​​​​SVG
3. Image Alt-Text
   • On channels that can display images, text that will be shown to the user when they hover over the image. On channels that do not support displaying images, this text will replace the image.
4. Image Width
   • Default
     • Uses the default image size based on the image size of the chat window.
   • Pixels
     • Uses a static pixel value for the size of the image
   • Percent
     • Uses a % of the viewer to assign a size to the image

Link

A hyperlink to a web resource. By default, the link will be presented directly to the bot user and if the user clicks on the link it will launch in a new browser window. A variety of options are available, however, to control exactly how the link is handles. Use this type to present links to web pages, images, videos, and files.

1. Automatically Open
   • Automatically open the content. If the content is a link and it is being sent to the slide-out and the link is https-based, the bot will open the link inside the slide-out; otherwise, the link will be opened in a popup window.
   • If the content is a form, the form will be displayed in a popup window if "Show in Slide-Out" is off or in the slide-out if "Show in Slide-Out" is on.
   • Note that some websites may not display in the slide-out because they refuse to be hosted in a frame. If this is the case, turn off auto-open or, if you control the website, include the bot in the list of allowable frame hosts.
2. Name
   • A name for the step that can be used to refer to it (and, therefore, the value of the entity) later in the intent flow.
3. Link
   • A link to a web resource.
4. Link Options
   • Optionally, the response can include a Link Preview or embedding if available. Both Link Preview and embedding are only available if supported by the host of the link. Link Preview requires the host to support the OpenGraph standard.
5. Bot Says
   • What the bot should say to the user. You can provide multiple versions and the bot will choose one at random. This can be used to make the bot seem more conversational or human.
     • Note that all text elements may include the following markdown formatting:
       • Bold: **text**
       • Italics: *text*
       • Link: [text](link)
       • Button: [[text]](link)
     • If the content type is Link, Form, Image, or Dynamic Credential, the following behavior is observed:
       • If no phrases are provided here, the user will be presented with the link directly (the URL will be visible).
       • If a phrase is provided here and it does not contain the macro text {{link}} or {{formlink}}, the user will be presented with the phrase and the entire phrase will link out to the provided URL or form.
       • If a phrase is provided here and it contains the macro text {{link}}, {{formlink}}, or {{host}}, the macro text will be replaced with the full URL or host as appropriate and the user will be presented with the resulting phrase. Use this in combination with the [text](link) markdown syntax to embed the link/form in the phrase, form example 'Please click [here]({{link}})'.
6. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.

Text

Plain text which may contain limited markdown.

1. Name
   • A name for the step that can be used to refer to it (and, therefore, the value of the entity) later in the intent flow.
2. Bot Says
   • What the bot should say to the user. You can provide multiple versions and the bot will choose one at random. This can be used to make the bot seem more conversational or human.
     • Note that all text elements may include the following markdown formatting:
       • Bold: **text**
       • Italics: *text*
       • Link: [text](link)
       • Button: [[text]](link)
     • If the content type is Link, Form, Image, or Dynamic Credential, the following behavior is observed:
       • If no phrases are provided here, the user will be presented with the link directly (the URL will be visible).
       • If a phrase is provided here and it does not contain the macro text {{link}} or {{formlink}}, the user will be presented with the phrase and the entire phrase will link out to the provided URL or form.
       • If a phrase is provided here and it contains the macro text {{link}}, {{formlink}}, or {{host}}, the macro text will be replaced with the full URL or host as appropriate and the user will be presented with the resulting phrase. Use this in combination with the [text](link) markdown syntax to embed the link/form in the phrase, form example 'Please click [here]({{link}})'.
3. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.

Text with Actions

Plain text, which may contain limited markdown, followed by one or more action buttons or links. The user can click on the buttons or links to submit further requests to the bot or launch external web pages.

1. Bot Says
   • What the bot should say to the user. You can provide multiple versions and the bot will choose one at random. This can be used to make the bot seem more conversational or human.
     • Note that all text elements may include the following markdown formatting:
       • Bold: **text**
       • Italics: *text*
       • Link: [text](link)
       • Button: [[text]](link)
     • If the content type is Link or Form, the following behavior is observed:
       • If no phrases are provided here, the user will be presented with the link directly (the URL will be visible).
       • If a phrase is provided here and it does not contain the macro text {{link}} or {{formlink}}, the user will be presented with the phrase and the entire phrase will link out to the provided URL or form.
       • If a phrase is provided here and it contains the macro text {{link}} or {{formlink}}, the macro text will be replaced with the URL and the user will be presented with the resulting phrase. Use this in combination with the [text](link) markdown syntax to embed the link/form in the phrase i.e. 'Please click [here]({{link}})'.
2. Render HTML
   • When checked, the content will be rendered as HTML on channels that support HTML. On channels that do not support HTML, any HTML tags present will be removed. When unchecked, the content is treated as plain text and HTML tags will appear as-is.
3. Actions
   • Actions that will be presented to the user. In the web channel, the actions are presented as buttons or links just below the primary 'say' content configured above; presentation in other channels will vary. If the user clicks an action button/link, the action associated with the button/link, as outlined below, will be executed.
   • You can configure an action with one text value, in which case the provided value is both shown to the user and used as the action. You can also configure an action using the markdown link syntax of [display text](action). In this case, the display text is shown to the user but the action is what is used to trigger the action. You can also include a description using markdown paragraph syntax (<p><description</p>). If buttons are used, the description will be shown as a tooltip when the user hovers over an action button. If links are used, the description is shown below the link.
   • If the action starts with 'http://' or 'https://', when the user selects it the specified link will be open in a web browser, when supported by the given channel. If a channel does not support a web browser, the link will be presented to the user. To override this behavior, preface the URL with the ^ symbol.
   • If the action does not start with 'http://' or 'https://', the action is sent to the bot server as a user utterance which will then trigger the matching intent.
4. Actions Presentation
   • Buttons
     • A button linking to a location
   • Links
     • An html link to a location