Easy message type creation in Studio

Teneo Web Chat supports various message types, allowing you to enrich your conversations with buttons, video's, cards etc. There are many ways you can add these message types to outputs in Teneo Studio, this page focusses on an approach that makes it easy to add message types using pre-defined properties.

Approaches to adding message types

Classic approach

To display message types, Teneo Web Chat looks for an output parameter teneowebclient. With the classic approach, you add the output parameter to the outputs where you want to the message type to appear and populate its value with the JSON as specified for the message type.

A common way to generate this JSON and populate the output parameter, is by using script nodes and flow variables.

Classic 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.

Simplified approach

While flexible and offering full control over the properties of message types, using script nodes and flow variables to add message types can be time consuming and requires understanding of Groovy and JSON. This page outlines an approach that simplifies adding message types, without needing to add script nodes or flow variables and without needing to understand the JSON format of the message types.

The simple output parameters approach, allows conversation designers in Studio to define message types by populating output parameters in a simplified and more intuitive way. For example, attaching an image to an output using this approach looks like this:

simple output parameter image

An output parameter called 'image' with the image url as value is all that is needed to attach the image. A post processing script takes care of converting the output parameter into the appropriate JSON that Teneo Web Chat expects.

Limitations

When using the simplified approach, 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, the classic approach can be used.

Setup

Before you can use simple output parameters, you will need to add the following two scripts to your solution:

  1. Add the file SimpleOpParser.groovy to the Resources in your solution and set the path to /script_lib
  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(_)

Because the SimpleOpParser class is used in the global Post Processing script, it is executed right before Teneo sends a response to Teneo Web Chat. SimpleOpParser looks for 'simple output parameters' in the response, uses those to create the JSON that Teneo Web Chat understands, adds a new output parameter teneowebclient to the response, populates it with the JSON and finally removes the 'simple output parameters' from the response.

Simple output parameters specification

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 classic 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 classic 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 classic 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_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 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
card Card Yes
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

Was this page helpful?