Rich Content Model
Root properties - required
property | required/optional | description |
|---|---|---|
type | required | The type of rich content. Should be set to options. |
name | Optional Default: empty string | A human readable name for the message for easier tracking of messages. It is not displayed. |
externalId | Optional | An optional unique id of the rich content message. By setting an externalId, navigations can be traced back to the message. |
bodyCss | Optional | The css applied on the body container. It can be flex for simpler content and grid for more advanced content. Or anything else really. If omitted it will fallback to the layout setting for rich content in the chat interaction or default to the vertical layout with flex column styling: |
body | required | Contains an array of objects which the user can interact with. When the user has interacted, the rich content becomes disabled or stays active based on the afterResponse setting. |
afterResponse | Optional Default: disable | A string identifier for what should happen to the UI after the user has made a selection. Supported values: disable: disables the richContent after a selection or confirmation of a selections is done. sticky: The richContent continues to be active after a selection is made. |
reponseMethod | Optional Default: optionsResponse
| This decides what should be sent after the user has interacted with the rich content. It can send an optionsResponse or a chat message with the values or both. Supported values: optionsResponse , chatMessage, both Using chatMessage will not disable the richContent when selecting an option, in effect making the content sticky
|
submitType | Optional Default: singleChoice | Decides if the a response should be sent on a single selection or using the submitButton. When using checkboxes, submitType needs to be set to multiChoice and a submitButton is needed. Supported values singleChoice multiChoice |
testFlow | Optional Default: should not be part of the data if not in test. | Test flow is used for end to end testing of bot flows. The property should not be exposed to customers. That means completely omitted. |
testFlow
Only to be used for test purposed. Not to be used in production, if used incorrectly the chat application may crash. Not to be used to set initial values for the richContent or similar.
Test flow is used for end to end testing of bot flows. It enables a simulation of user choices and responses. It’s an array with commands that will be executed in order.
Keep in mind that disabled buttons can still be clicked using testFlow. This means that buttons that have already been submitted can be clicked again.
Make sure that all buttons that are clicked actually exist in the richContent. Using click on missing buttons and submit button could generate errors or a crash.
If a new richContent with testFlow is received during an ongoing testFlow the commands will be interleaved creating unpredictable results.
testFlow commands
command | description |
|---|---|
| This will click a button with the id. It works on both multi select and single select buttons. |
| This will click the submit button and trigger the submission. The id needs to be set to ‘submit’ |
| This will set the text of an input with id to value. |
| This will do a wait for the number of milliseconds in value. The wait command can be used the interaction more humanlike. |
| This will send a regular chat message. |
button
When a button is pressed the responseMethod and subsequently the afterResponse is executed.
property | required/optional | description |
|---|---|---|
type | required | Is set to button |
id | required | The id of the button |
label | required | The label displayed on the button |
value | required | The value of the button |
icon | optional Default: empty string | When set adds an icon in front of the label. The icon is defined by a string name. |
group | optional Default: singleChoice | Optional parameter. Should be left unset unless using buttons as radio buttons. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
sticky | optional Default: false | When sticky is enabled the item remains active after the richContent is disabled. This is particularly usefull for thumb buttons which need to be accesible at all times. This is not to be confused with the afterResponse setting which makes the entire content sticky. |
Example
{
type: 'button',
id: 'id1',
label: 'Choice 1',
value: 'value1'
}
symbol
A symbol that works like a button like thumbs up or down.
property | required/optional | description |
|---|---|---|
type | required | Is set to symbol |
id | required | The id of the symbol |
value | required | The value of the symbol |
icon | required | The icon of the symbol. |
size | optional Default: ‘30px’ | The size sets the width and height of the symbol. |
group | optional Default: singleChoice | Should be set to something specific when using thumbs. Make sure all thumbs have are in the same group. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
attributes | optional | Supported attributes: aria-labelis a good idea to add for accesibility. Any other attributes that are in attribues will also be used. |
sticky | optional Default: false | Set to true for sticky thumb buttons. |
Example
{
type: 'symbol',
id: 'id1',
icon: 'faThumbsUp',
group: 'thumbs',
value: 'value1'
}
checkbox
A checkbox element. It does not send a response when clicked. Use in conjunction with a submitButton.
Set submitType to multiChoice
property | required/optional | description |
|---|---|---|
type | required | Is set to checkbox |
id | required | The id of the checkbox |
label | required | The label displayed next to the checkbox |
value | required | The value of the checkbox |
group | required
| The group that the checkbox belogns to. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
sticky | optional Default: false | The checkbox should not be set to sticky. Use afterResponse sticky instead. |
attributes | optional | Supported attributes: required This will make the checkbox mandatory. |
Example
{
type: 'checkbox',
label: 'Choice 1',
id: 'id1',
value: 'value1',
group: 'checkboxGroup'
}
submitButton
When the submitButton is pressed it sends a response based on responseMethod.
The submit button is active even when the user hasn’t made a choice. This maybe needs to change in the future.
Set submitType to multiChoice to enable the button.
property | required/optional | description |
|---|---|---|
type | required | Is set to submitButton |
label | required | The label displayed on the button |
icon | optional Default: empty string | When set adds an icon in front of the label. The icon is defined by a string name. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
Example
{
type: 'submitButton',
label: 'submit'
}linkButton
Opens a link and sends a response.
Keep in mind that links can be added using the text item aswell. The difference is that the linkButton response can be traced back to the original message using externalId and the linkButton id.
property | required/optional | description |
|---|---|---|
type | required | Is set to linkButton |
id | required | The id of the button. This id is used when sending newTabNavigation |
label | required | The label displayed on the button |
icon | optional Default: faArrowUpRightFromSquare | An Icon is default but can be changed. At the moment it’s not possible to remove the icon, only change it. |
url | required | The url. |
target | optional | This is not used. Links to other domains will automatically open in a new tab. |
value | optional | This is not used. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
sticky | optional Default: false | When sticky is enabled for an item remains active after the richContent is disabled. |
Example
{
label: 'puzzel.com',
type: 'linkButton',
id: 'buttonId',
url: 'https://www.puzzel.com'
}
input
A text input field. This can be used to create a form.
property | required/optional | description |
|---|---|---|
type | required | Is set to input |
id | required | The id of the input |
label | optional | This is not used |
value | optional default: empty string | The value of the input works differently than for single choice components. If a value is provided it will be used as a defatult value in the input. When an optionsResponse is sent the value of the input item will correspond to the entered text in the input. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
sticky | optional Default: false | The input should not be set to sticky. Use afterResponse sticky instead. |
attributes | optional | Supported attributes: required This will make the input mandatory. type: default is text Any other attributes that are in attribues will also be used. for example placeholder, autoComplete, minLength, maxLength and pattern. |
Example
{
type: 'input',
id: 'id1',
value: '',
css: {
...
},
attributes: {
required: true,
placeholder: 'Enter your name',
autoComplete: 'given-name'
}
}
Select
A dropdown for selecting single items. To be used in a form
property | required/optional | description |
|---|---|---|
type | required | Is set to select |
id | required | The id of the select |
|
|
|
value | optional default: empty string | The value of the select. Works like an input. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
sticky | optional Default: false | The select should not be set to sticky. Use afterResponse sticky instead. |
attributes | optional | Supported attributes: required This will make the select mandatory. aria-labelis a good idea to add for accesibility. Any other attributes that are in attribues will also be used. |
options | required | Options is an array of objects containing value and label for the entries in the select. |
Example
{
type: 'select',
id: 'id1',
value: '',
css: {
...
},
attributes: {
...
},
options: [
{ value: '', label: 'Select country' },
{ value: 'SE', label: 'Sweden' },
...
]
}Text
A text element that supports markdown.
property | required/optional | description |
|---|---|---|
type | required | Is set to text |
text (plain text or markdown) | Optional Default: empty string | The displayed text. If omitted or set to empty it won’t be displayed. This can be used to show only afterResponseText. |
afterResponseText (plain text or markdown) | Optional Default: empty string | The text shown when the user has made a selection. If it’s empty or undefined it will use the text property instead. |
css | optional Default: empty object | The css applied to the container that contains the item. Use it for grid item styling. |
Example
{
type: 'text',
text: 'Please select',
afterResponseText: 'Good choice'
}
Response data format
The format of the data being sent to the endpoint /api/conversation/{id}/data when the user confirms a selection. The response supports single and multi choice selections. The data sent back is reduced of uneccessary properties and is not identical to the original.
This response is only sent by the visitor
LinkButton does not send an optionsResponse but a newTabNavigation.
Root parameters
Parameter | Value |
|---|---|
dataType | Is set to optionsResponse |
data | The data |
Data parameters
Parameter | Value |
|---|---|
eventId | The eventId of the chat message that contained the richContent. This is used by frontend |
externalId | The id of the richContent that the user has interacted with. |
nextStatus | Parameter used by frontend to handle sticky. |
selection | An array with the selected options |
Item parameters in the selection array
Parameter | Value |
|---|---|
id | The id of the element that the user has interacted with. |
value | The value of the element that the user has interacted with. |
type | The type of the element that the user has interacted with. |
Example
{
dataType: 'optionsResponse',
data: {
eventId: 'chat message eventId',
externalId: 'externalId',
selection: [
{
id: 'buttonId',
type: 'button'
value: 'buttonValue',
}
]
}
}Rich content examples
Small example
A small example without bodyCss using the default layout setting in the chat interaction.
{
type: 'options',
name: 'small',
externalId: 'externalId1',
body: [
{
type: 'button',
label: 'Choice 1',
id: 'id1',
value: 'value1'
},
{
type: 'button',
label: 'Choice 2',
id: 'id2',
value: 'value2'
}
]
}
Sticky example
Simple example with two choices using flex for styling. AfterResponse set to sticky so the user can reselect. Using responseMethod both to send both an optionsResponse and a chatMessage.
{
type: 'options',
name: 'sticky, flex',
externalId: 'externalId1',
afterResponse: 'sticky',
responseMethod: 'both',
bodyCss: {
display: 'flex',
flexDirection: 'column',
alignItems: 'center',
gap: '4px'
},
body: [
{
type: 'text',
text: 'sticky, flex'
},
{
type: 'button',
label: 'Choice 1',
id: 'id1',
value: 'value1'
},
{
type: 'button',
label: 'Choice 2',
id: 'id2',
value: 'value2'
}
]
}
Thumbs example
Two choices and a link button. When the user has made a choice the buttons are disabled. The layout uses grid to place two thumb buttons next to eachother on the right side. The thumb buttons are sticky and continue to work after the other options have been disabled.
{
type: 'options',
name: 'grid, thumbs',
externalId: 'externalId2',
bodyCss: {
display: 'grid',
gridTemplateColumns: '2fr 1fr',
gridAutoRows: '1fr',
gridGap: '4px'
},
body: [
{
type: 'text',
text: 'grid, thumbs',
css: {
gridColumn: '1 / span 2',
justifySelf: 'center'
}
},
{
type: 'button',
label: 'Choice 1',
id: 'id1',
value: 'value1',
css: {
gridColumn: '1 / span 2',
justifySelf: 'center'
}
},
{
type: 'button',
label: 'Choice 2',
id: 'id2',
value: 'value2',
css: {
gridColumn: '1 / span 2',
justifySelf: 'center'
}
},
{
type: 'linkButton',
label: 'link',
url: 'https://www.puzzel.com',
id: 'id4',
value: 'value2',
css: {
gridColumn: '1 / span 2',
justifySelf: 'center'
}
},
{
type: 'symbol',
icon: 'faThumbsUp',
id: 'id5',
group: 'yesNo',
value: 'yes',
sticky: true,
css: {
gridColumn: '1',
justifySelf: 'right'
}
},
{
type: 'symbol',
icon: 'faThumbsDown',
id: 'id6',
group: 'yesNo',
value: 'no',
sticky: true,
css: {
gridColumn: '2',
justifySelf: 'left'
}
}
]
}
Submit example
An example using submitType multiChoice. A grid with three checkboxes and a submit button, thumb buttons, a markdown link and an after response text. The thumb buttons have been resized using size.
{
type: 'options',
name: 'submit example',
externalId: 'externalId3',
submitType: 'multiChoice',
bodyCss: {
display: 'grid',
gridTemplateColumns: '2fr 1fr 1fr',
gridAutoRows: 'auto',
gridGap: '10px'
},
body: [
{
type: 'text',
text: 'Submit example',
css: {
gridColumn: '1 / span 3',
justifySelf: 'center'
}
},
{
type: 'checkbox',
label: 'Stay hungry',
id: 'id1',
value: 'stayHungry',
group: 'checkboxGroup',
css: {
justifySelf: 'start',
gridColumn: '1 / span 3'
}
},
{
type: 'checkbox',
label: 'Built on trust',
id: 'id2',
value: 'builtOnTrust',
group: 'checkboxGroup',
css: {
justifySelf: 'start',
gridColumn: '1 / span 3'
}
},
{
type: 'checkbox',
label: 'Stronger together',
id: 'id3',
value: 'strongerTogether',
group: 'checkboxGroup',
css: {
justifySelf: 'start',
gridColumn: '1 / span 3'
}
},
{
type: 'submitButton',
label: 'Submit',
css: {
justifySelf: 'center',
gridColumn: '1 / span 3'
}
},
{
type: 'text',
text: '',
afterResponseText: 'Thank you',
css: {
justifySelf: 'center',
gridColumn: '1 / span 3'
}
},
{
type: 'text',
text: '[link](https://www.puzzel.com)',
css: {
gridColumn: '1',
justifySelf: 'start',
alignSelf: 'center'
}
},
{
type: 'symbol',
icon: 'faThumbsUp',
id: 'id4',
group: 'yesNo',
value: 'yes',
size: '20px',
sticky: true,
css: {
gridColumn: '2',
justifySelf: 'right',
alignSelf: 'center'
}
},
{
type: 'symbol',
icon: 'faThumbsDown',
id: 'id5',
group: 'yesNo',
value: 'no',
size: '20px',
sticky: true,
css: {
gridColumn: '3',
justifySelf: 'left',
alignSelf: 'center'
}
}
]
}
Form Example
{
type: 'options',
name: 'form example',
externalId: 'externalId3',
submitType: 'multiChoice',
responseMethod: 'both',
bodyCss: {
display: 'grid',
gridTemplateColumns: '1fr 1fr 1fr .5fr',
gridAutoRows: 'auto',
gridGap: '10px'
},
body: [
{
type: 'text',
text: 'Form example',
css: {
gridColumn: '1 / span 4',
justifySelf: 'center'
}
},
{
type: 'input',
label: 'name',
id: 'id1',
value: '',
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
},
attributes: {
required: true,
placeholder: 'Enter your name',
autoComplete: 'given-name'
}
},
{
type: 'input',
label: 'lastName',
id: 'id2',
value: '',
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
},
attributes: {
required: true,
placeholder: 'Enter your last name',
autoComplete: 'family-name'
}
},
{
type: 'input',
label: 'email',
id: 'id3',
value: '',
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
},
attributes: {
required: true,
placeholder: 'Enter your email',
autoComplete: 'email'
}
},
{
type: 'select',
id: 'id7',
value: '',
options: [
{ value: '', label: 'Select country' },
{ value: 'SE', label: 'Sweden' },
{ value: 'NO', label: 'Norway' },
{ value: 'DK', label: 'Denmark' },
{ value: 'FI', label: 'Finland' }
],
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
},
attributes: {
required: true
}
},
{
type: 'checkbox',
label: 'Agree to terms',
id: 'id4',
value: 'test',
group: 'checkboxGroup',
css: {
alignSelf: 'center',
justifySelf: 'center',
gridColumn: '1 / span 2'
},
attributes: {
required: true
}
},
{
type: 'text',
text: '[terms](https://www.puzzel.com)',
css: {
gridColumn: '3',
justifySelf: 'start',
alignSelf: 'center'
}
},
{
type: 'submitButton',
label: 'Submit',
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
}
},
{
type: 'symbol',
icon: 'faThumbsUp',
id: 'id5',
group: 'yesNo',
value: 'yes',
size: '20px',
sticky: true,
css: {
gridColumn: '3',
justifySelf: 'right',
alignSelf: 'center'
}
},
{
type: 'symbol',
icon: 'faThumbsDown',
id: 'id6',
group: 'yesNo',
value: 'no',
size: '20px',
sticky: true,
css: {
gridColumn: '4',
justifySelf: 'left',
alignSelf: 'center'
}
}
]
}
testFlow example
Example with a testflow with button clicks, input fills, submit click, chat message and some delays.
{
type: 'options',
name: 'testFlow example',
externalId: 'externalId2',
submitType: 'multiChoice',
bodyCss: {
display: 'grid',
gridTemplateColumns: '2fr 1fr',
gridAutoRows: '1fr',
gridGap: '4px'
},
body: [
{
type: 'text',
text: 'Test flow example',
css: {
gridColumn: '1 / span 3',
justifySelf: 'center'
}
},
{
type: 'checkbox',
label: 'test1',
id: 'id1',
value: 'test1',
group: 'checkboxGroup',
css: {
justifySelf: 'start',
gridColumn: '1 / span 3'
}
},
{
type: 'input',
label: 'test2',
id: 'id2',
value: '',
css: {
justifySelf: 'center',
gridColumn: '1 / span 4'
}
},
{
type: 'submitButton',
label: 'Submit',
css: {
justifySelf: 'center',
gridColumn: '1 / span 3'
}
},
{
type: 'symbol',
icon: 'faThumbsUp',
id: 'id4',
group: 'yesNo',
value: 'yes',
size: '20px',
sticky: true,
css: {
gridColumn: '2',
justifySelf: 'right',
alignSelf: 'center'
}
},
{
type: 'symbol',
icon: 'faThumbsDown',
id: 'id5',
group: 'yesNo',
value: 'no',
size: '20px',
sticky: true,
css: {
gridColumn: '3',
justifySelf: 'left',
alignSelf: 'center'
}
}
],
testFlow: [
{
type: 'wait',
value: 2000
},
{
type: 'click',
id: 'id1'
},
{
type: 'input',
id: 'id2',
value: 'hej'
},
{
type: 'wait',
value: 2000
},
{
type: 'click',
id: 'submit'
},
{
type: 'wait',
value: 2000
},
{
type: 'click',
id: 'id5'
},
{
type: 'wait',
value: 2000
},
{
type: 'chatMessage',
value: 'I want to talk to a human'
}
]
}