Teneo Developers

Easy message type creation in Studio

Simple Output Parameters make it easy to enrich your conversations with for example buttons, video's and cards in Teneo Web Chat.

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

This page focuses 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:

Teneo Web Chat - Output param

Prepare your solution

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

  1. Add the file SimpleOpParser 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.

Teneo Web Chat - Output params 2

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.

Teneo Web Chat - Output Params Video

Teneo Web Chat supports three different types of videos:

  • Hosted video files
  • Vimeo videos
  • YouTube videos

Note that 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:

BrowserMP4WebMOGG
EdgeYESYESYES
ChromeYESYESYES
FirefoxYESYESYES
SafariYESYESNO
OperaYESYESYES

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.

Teneo Web Chat - Output Params - Audio

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

BrowserMP3WAVOGG
EdgeYESNONO
ChromeYESYESYES
FirefoxYESYESYES
SafariYESYESNO
OperaYESYESYES

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.

Teneo Web Chat - Output System

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.

Teneo Web Chat - Output Param Quickreply

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

Teneo Web Chat - Output Params with buttons

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 bot after clicking the button

Buttons work similarly to quick replies 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.

Teneo Web Chat - Output params with clickable list

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 bot after clicking the clickable items

The clickable list works similarly to quick reply when created with simple output parameters, except clickable lists don'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.

Teneo Web Chat - Output Links buttons

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

Teneo Web Chat - Cards 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.

Teneo Web Chat - Output params with cards

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

Output parameter nameExample valueComments
card_titleThis is the titlePlain text as value
card_subtitleThis is the subtitlePlain text as value
card_bodytextThis is the body textPlain text as value
card_imagehttps://address/image.pngURL of image, use the pipe symbol ('|') as separator for alternative text
card_buttonsButton 1, Button 2, Button 3Use the pipe symbol ('|') as the separator
card_clickablelistOption 1, Option 2, Option 3Use the pipe symbol ('|') as the separator
card_linkbuttonsLink 1, https://link1.html,_blank Link 2, https://link2.htmlUse comma as separator between text, URL and (optional) target; Use the pipe symbol ('|') the as separator between hyperlinks
card_linksLink 1, https://link1.html Link 2, https://link2.htmlUse comma as separator between text and URL; Use the pipe symbol ('|') the as separator between hyperlinks.

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.

Modal

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 bot until they've clicked one of the buttons in the modal window.

Teneo Web Chat - Modal

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.

Teneo Web Chat - Modal 11

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

Output parameter nameExample valueComments
modal_titleThis is the titlePlain text as value
modal_bodytextThis is the body textPlain text as value
modal_imagehttps://address/image.pngURL of image, use the pipe symbol ('|') as separator for alternative text
modal_buttonsButton 1, Button 2, Button 3Use 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.

Teneo Web Chat - Combo Order

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

Type nameMessage typeSupported in combo
audioAudioYes
buttonsButtonsYes
linkbuttonsLink buttonsYes
cardCardYes
carouselCarouselNo
imageImageYes
listClickable listYes
modalModal windowNo
quickreplyQuick reply buttonsYes
systemSystem messageNo
textText bubbleYes
videoVideoYes

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

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

Teneo Web Chat - Advanced

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

groovy

1// Parse simple output parameters for Teneo Web Chat message types     
2SimpleOpParser.parseParams(_)
3