Easy message type creation in Studio

Teneo Web Chat supports various rich message types, allowing you to enrich your conversations with buttons, video's, cards etc. There are different ways to add these rich messages to outputs in Teneo Studio.

This page focusses on an approach that makes it easy to add rich message types by adding a few helpful scripts to your solution.

Once added, conversation designers in Studio can add rich messages by populating output parameters in a simplified and intuitive way. For example, attaching an image to an output using this approach is as simple as adding an output parameter with the url of the image:

simple output parameter image

Prepare your solution

First, we'll prepare our solution by adding two scripts:

  1. Add the file SimpleOpParser.groovy to the Resources in your solution and set the path to /script_lib
    • You can also find the source code on Github.
  2. Add the following lines of code at the bottom of the 'Post Processing' script in Global Scripts:
    // parse simple output parameters for Teneo Web Chat message types
    SimpleOpParser.parseParams(_)

Adding rich messages

Once we've added the two scripts, we can start adding output parameters with message type details to our outputs. We'll refer to these output parameters as simple output parameters going forward.

Image

To display an image in Teneo Web Chat using simple output parameters, you need to add an output parameter named image and assign the image's URL to the output parameter's value. The supported image formats are jpeg, gif, png, apng, svg, bmp and ico. You can also add an optional alternative text after the URL, with a pipe symbol ('|') as the separator.

output parameter named image with an url to an image

Video

To display a video in Teneo Web Chat using simple output parameters, you need to add an output parameter named video and assign the video's URL to the output parameter's value.

output parameter named video with the value containing an Youtube embed URL

Teneo Web Chat supports three different types of videos:

  • Hosted video files
  • Vimeo videos
  • YouTube videos

Note when adding a Youtube video, you'll have to use the embed URL, for example, an embed URL for Youtube would look like this: https://www.youtube.com/embed/VIDEO_ID. For hosted video files, the supported video formats are MP4, WebM, and OGG. The table below shows the hosted video format and browser compatibility:

Browser MP4 WebM OGG
Edge YES YES YES
Chrome YES YES YES
Firefox YES YES YES
Safari YES YES NO
Opera YES YES YES

Audio

To display an audio player in Teneo Web Chat using simple output parameters, you need to add an output parameter named audio and assign the audio's URL to the output parameter's value.

output parameter named audio with the value containing an URL pointing to a MP3 file

The supported audio formats are MP3, WAV, and OGG. The table below shows the audio format and browser compatibility:

Browser MP3 WAV OGG
Edge YES NO NO
Chrome YES YES YES
Firefox YES YES YES
Safari YES YES NO
Opera YES YES YES

System message

To display a system message in Teneo Web Chat using simple output parameters, you need to add an output parameter named system and assign the text message to the output parameter's value.

output parameter named system with the value containing a system text message

Quick reply

To display quick reply options in Teneo Web Chat using simple output parameters, you need to add an output parameter named quickreply and assign the options to the output parameter's value. Use the pipe symbol ('|') to separate the options.

output parameter named quickreply with the value containing different quickreply options separated by pipe

The JSON for each quick reply option consists of three elements:

  • Style - represents the color of the quick reply option
  • Title - represents the quick reply option text
  • Postback - represents the text sent to the Chatbot after clicking the quick reply option

When working with Quick replies and simple output parameters, you only have to define the title. Style is by default 'primary' and postback automatically gets assigned the value of the title. If your bot requires other styles or postback values, you should add the message type using the advanced approach.

Buttons

To display buttons in Teneo Web Chat using simple output parameters, you need to add an output parameter named buttons and assign the button texts to the output parameter's value. Use the pipe symbol ('|') to separate the button texts. If you want to add a title to your buttons, create another output parameter named buttons_title and assign the title text to the output parameter's value.

two output parameters. One named buttons containing the buttons text, the other is named buttons_title containing the title text

The JSON for each button option consists of three elements:

  • Style - represents the color of the button
  • Title - represents the button text
  • Postback - represents the text sent to the Chatbot after clicking the button

Buttons work similarly to quick reply when used together with simple output parameters. Style is by default primary and postback automatically gets assigned the value of the title. If your bot requires other styles or postback values, you should add the message type using the advanced approach.

Clickable list

To display a clickable list in Teneo Web Chat using simple output parameters, you need to add an output parameter named clickablelist and assign the options to the output parameter's value. Use the pipe symbol ('|') to separate the options. If you want to add a title to your clickable list, create another output parameter named clickablelist_title and assign the title text to the output parameter's value.

two output parameters. One named clickablelist containing the clickable options, the other is named clickablelist_title containing the title text

The JSON for each item in the clickable list consists of two elements:

  • Title - represents the clickable item's text
  • Postback - represents the text sent to the Chatbot after clicking the clickable items

The clickable list works similarly to quick reply when created with simple output parameters, except clickable list doesn't contain the style element. Postback automatically gets assigned the value of the title. If your bot requires custom postback values, you should add the message type using the advanced approach.

To display link buttons in Teneo Web Chat using simple output parameters, you need to add an output parameter named linkbuttons and assign the link button details (text, url and optional target) to the output parameter's value. Use the pipe symbol ('|') to separate the button details. If you want to add a title to your link buttons, create another output parameter named linkbuttons_title and assign the title text to the output parameter's value.

Output parameters for linkbuttons

The JSON for each button option consists of three elements:

  • Title - represents the button text
  • Url - the url that will be opened when the user clicks the button
  • Target - defines target, to allow links to be opened in a new tab

If your bot requires additional details to be included in a linkbutton, you should add the message type using the advanced approach.

Card

A card In Teneo Web Chat refers to a box that contains at least one of the following components:

  • An image
  • A title, subtitle or a body text
  • Buttons, links or a clickable list

Card with links

To display a card in Teneo Web Chat using simple output parameters, you need to use the prefix card_ when naming the output parameters. For example, to display an image, you would name the output parameter card_image. Then assign the corresponding content to the output parameter's value. Note that all the card components are optional, however, you need to include at least one component to display the card properly.

multiple output parameters named with the card prefix 'card' containing corresponding content

The table below shows the different card components that are supported:

Output parameter name Example value Comments
card_title This is the title Plain text as value
card_subtitle This is the subtitle Plain text as value
card_bodytext This is the body text Plain text as value
card_image https://address/image.png|alt text Url of image, use the pipe symbol ('|') as separator for alternative text
card_buttons Button 1|Button 2|Button 3 Use the pipe symbol ('|') as the separator
card_clickablelist Option 1|Option 2|Option 3 Use the pipe symbol ('|') as the separator
card_linkbuttons Link 1,https://link1.html,_blank|Link 2,https://link2.html Use comma as separator between text, URL and (optional) target; Use the pipe symbol ('|') the as separator between hyperlinks
card_links Link 1,https://link1.html|Link 2,https://link2.html Use comma as separator between text and URL; Use the pipe symbol ('|') the as separator between hyperlinks.
Note: card_links are deprecated and will be removed in the next major release of Teneo Web Chat. Please use card_linkbuttons instead.

Note that the order in which you create the output parameters doesn't affect how the card is displayed in Teneo Web Chat.

In Teneo Web Chat, a 'modal' refers to a modal window that disables the main chat window. Users will not able to use the text input field nor the corner buttons to minimize or close the chatbot until they've clicked one of the buttons in the modal window.

Example of a modal message

To display a modal window in Teneo Web Chat using simple output parameters, you need to add multiple output parameters with the prefix modal_, for example, modal_image and modal_title. Then assign the corresponding content to the output parameter's value. Note that all the modal components are optional, however, you need to include at least one button, or else the users will not be able to close the modal window.

multiple output parameters with the modal prefix 'modal_' containing corresponding content

The table below shows the different modal components that are supported:

Output parameter name Example value Comments
modal_title This is the title Plain text as value
modal_bodytext This is the body text Plain text as value
modal_image https://address/image.png|alt text Url of image, use the pipe symbol ('|') as separator for alternative text
modal_buttons Button 1|Button 2|Button 3 Use the pipe symbol ('|') as the separator

Note that the order in which you create the output parameters doesn't affect how the modal is displayed in Teneo Web Chat.

Combo

In Teneo Web Chat, a 'combo' refers to an output that contains more than one message type.

To display a combo in Teneo Web Chat using simple output parameters, you need to have at least two different message types added to the same output node. The simple output parameter parser will then automatically detect that there is more than one message type, and create a combo for you.

Combo order

If you want to order the message types in your combo in a specific way, you can add a special output parameter called combo_order to specify the order of the components. If not specified, the order will be random. The value of the 'combo_order' parameter should contain the type names separated by the pipe symbol ('|') in the order that you want them.

multiple output parameters named after type containing corresponding content and one output parameter named 'modal_order' containing the order of the types

Note that not all message types can be used in combo messages, as outlined in the table below:

Type name Message type Supported in combo
audio Audio Yes
buttons Buttons Yes
linkbuttons Link buttons Yes
card Card Yes
carousel Carousel No
image Image Yes
list Clickable list Yes
modal Modal window No
quickreply Quick reply buttons Yes
system System message No
text Text bubble Yes
video Video Yes

Advanced approach

As described in the Teneo Web Chat message type JSON specification, Teneo Web Chat looks for an output parameter teneowebclient. The approach outlined on this page uses the SimpleOpParser class which produces the correct JSON by converting the details provided in 'simple output parameters'.

Thus simplified approach has some limitations. Some message types will be added with certain default values. For example, buttons will get the style 'primary' and the postback value will be the same as the title of the button.

In cases where more customization is needed, you can generate the JSON and populate the teneowebclient output parameter using script nodes and flow variables. This gives you full control over the JSON that is added to the output parameter.

Advanced approach using script node

A step by step explanation of this approach can be found in 'How to populate output parameters' in the 'Build your bot' section.

Was this page helpful?