Timeline Markup

Timeline Markup is used to send advanced UI elements from our design kit to users.

Table of Contents

Introduction To Timeline Markup

Timeline Markup can be combined with “context” from other sources and using Apache’s Velocity Template Language you can dynamically assemble an interface using a number of existing components.

Timeline Markup is strict XML. All the rules of XML apply and an XML validator will at least tell you if your markup is well formed.

TimelineMessage

  • The top level element for the Timeline
  • All Timeline Components must be contained in the TimelineMessage element

There is a 100kb limit on messages. If a message is larger than that it will not appear in the timeline. When creating a message with multiple base64 images, e.g. a carousel, ensure that the combined size of the images is under 100kb.

The parameters for a TimelineMessage are:

Name Type Default Values Description
minimumDisplayTime number 1 second between 1 and 5 the number of seconds before the next message should display

An example of the simplest TimelineMessage element is:

<TimelineMessage>
  <TextMsg>Hello</TextMsg>
</TimelineMessage>

Timeline messages can also delay the message that comes after it by using the minimumDisplayTime:

<TimelineMessage minimumDisplayTime="1.5">
  <TextMsg>Hello</TextMsg>
</TimelineMessage>

You can send multiple timeline elements in one message

<TimelineMessage>
  <TextMsg>Hello</TextMsg>
  <TextMsg>Second Message</TextMsg>
</TimelineMessage>

Interaction Types

Selectable timeline elements can generate either utterances or markup interactions when the user selects items.

  • For utterances: interactionType='utterance' (default)
  • For markup interactions: interactionType='event'

Event Supported Elements

  • Broadcast Messages
  • Buttons
  • Detail View
  • Drop-downs
  • File Uploads
  • Lists (Selectable)
  • Maps (Get User’s Location)
  • Suggested Prompts
  • Star Ratings

Example broadcast message using markup interactions

<TimelineMessage>
  <BroadcastMsg
     title="Warning"
     body="This fund will be discontinued next month. We'll be moving you to another fund."
     style="warning"
     interactionType="event">
       <Option title="Select alternative fund" id="1234" />
  </BroadcastMsg>
</TimelineMessage>

Example buttons using markup interactions

<TimelineMessage>
    <ButtonPromptContainer interactionType="event">
      <ButtonPrompt label="Option One" id="1"/>
      <ButtonPrompt label="Option Two" id="2"/>
    </ButtonPromptContainer>
</TimelineMessage>

Example detail view using markup interactions

<TimelineMessage>
  <DetailView
    title="ServisBOT"
    description="Check out our bots"
    url="https://servisbot.com"
    interactionType="event"
  />
</TimelineMessage>

Example dropdown using markup interactions

<TimelineMessage>
  <Dropdown value="3" title="When would you like to set it?" interactionType="event">
    <DropdownItem id="1" title="Option 1" />
    <DropdownItem id="2" title="Option 2" />
    <DropdownItem id="3" title="Option 3" />
  </Dropdown>
</TimelineMessage>

Example file upload using events

<TimelineMessage>
    <FileUpload promptText="Could you provide photos of the front and back of your licence?" promptButtonText="Upload Pictures" retryButtonText="Replace" confirmationText="All set!" confirmButtonText="Complete" interactionType="event">
      <UploadItem fileType="image/*" label="Front" name="LicenceFront"/>
      <UploadItem fileType="image/*" label="Back" name="LicenceBack"/>
    </FileUpload>
</TimelineMessage>

Example list using events

<TimelineMessage>
  <List title="Please select a number" selectable="true" interactionType="event">
     <Item title="Option one is here" id="1"/>
     <Item title="Option two is here" id="2"/>
     <Item title="Option three is here" id="3"/>
     <Item title="Option four is here" id="4"/>
  </List>
</TimelineMessage>

Example map using Markup interactions

<TimelineMessage>
  <StaticMap
    title="Please confirm your location"
    interactionType="event"
  />
</TimelineMessage>

Example Suggested Prompts using markup interactions

<TimelineMessage>
    <SuggestionPrompt interactionType="event">
      <Option title="30 x 30" id="1111" />
      <Option title="32 x 32" id="2222" />
      <Option title="33 x 32" id="3333" />
      <Option title="34 x 34" id="4444" />
      <Option title="35 x 34" id="5555" />
      <Option title="v36 x 36" id="6666" />
      <Option title="v37 x 35" id="7777" />
      <Option title="v38 x 36" id="8888" />
    </SuggestionPrompt>
  </TimelineMessage>

Example star rating using markup interactions

<TimelineMessage>
  <StarRating
    title="Can you please rate our service today?"
    maxValue="5"
    preventRetries="true"
    interactionType="event"
  />
</TimelineMessage>

Timeline Elements

The general parameters for all Timeline Element are:

Name Type Default Values Description
dir string ltr ltr,rtl specifies the text direction of an element (left-to-right, right-to-left)

An example of the simplest TimelineMessage element with Right-To-Left direction is:

<TimelineMessage>
  <TextMsg dir="rtl">Hello</TextMsg>
</TimelineMessage>

Broadcast

Dismissible message at the top of the feed (default):

Display for number of seconds (displayTime param)

The parameters for Broadcast are:

Name Type Default Values Description
style string none error, warning, info the style of the message
title string - - the title of the message
body string - - the body of the message
displayTime (optional) string number of seconds the message to be shown - number of seconds

If no displayTime is provided the Broadcast message will be closeable (a small ‘x’ in the top right corner)

An example of Broadcast Markup is:

<TimelineMessage>
  <BroadcastMsg
      style="error"
      title="Something's gone wrong!"
      body="Please provide a first name. Please provide a valid email address. Error uploading image. Please try again."
      displayTime="5"
    />
</TimelineMessage>

Broadcast with Options

A call to action displayed at the bottom of the broadcast message.

The parameters for Option are:

Name Type Default Values Description
title string - - the title of the message
id string - - identifier for the action
url string - - url which can be opened in a webview
urlTitle string - - the title of the webview that the url will be opened in
linkOpenTarget string - - open item url in a new tab tab, in webview messenger or change the current parent page self
interactionType string utterance utterance, event
  • Event fires a markup interaction with the option selected
  • Utterance adds a message to the timeline with the option selected

An example of Option Markup is:

<TimelineMessage>
 <BroadcastMsg
   title="Warning"
   body="This fund will be discontinued next month. We'll be moving you to another fund."
   style="warning">
     <Option title="Select alternative fund" id="1234" />
  </BroadcastMsg>
</TimelineMessage>

To use this markup with as a markup interaction node, simply add interactionType="event"

<TimelineMessage>
  <BroadcastMsg
     title="Warning"
     body="This fund will be discontinued next month. We'll be moving you to another fund."
     style="warning"
     interactionType="event">
       <Option title="Select alternative fund" id="1234" />
  </BroadcastMsg>
</TimelineMessage>

See also: BroadcastMsg, SuggestionPrompt, List

Button Prompts

Provide Available Responses to users with within the timeline. This component has a different layout depending on how many options you provide

The parameters for Option are:

Name Type Default Values Description
url string - - url that can be opened from the messenger
linkOpenTarget string tab tab,self open item url in a new tab tab, or change the current parent page self

One Column Default Display

  <TimelineMessage>
    <ButtonPromptContainer>
      <ButtonPrompt label="Option One" id="0"/>
      <ButtonPrompt label="Option Two" id="1"/>
      <ButtonPrompt label="Option Three" id="2"/>
    </ButtonPromptContainer>
  </TimelineMessage>

Two Column Display

<TimelineMessage>
  <ButtonPromptContainer display="two-column">
    <ButtonPrompt label="Option One" id="0"/>
    <ButtonPrompt label="Option Two" id="1"/>
  </ButtonPromptContainer>
</TimelineMessage>

Inline Flowed Display

<TimelineMessage>
  <ButtonPromptContainer display="inline">
    <ButtonPrompt label="Option One" id="1"/>
    <ButtonPrompt label="Option Two" id="2"/>
    <ButtonPrompt label="Three" id="3"/>
    <ButtonPrompt label="Option Four" id="4"/>
    <ButtonPrompt label="Option Five" id="5"/>
    <ButtonPrompt label="Option Six" id="6"/>
  </ButtonPromptContainer>
</TimelineMessage>

Calendar

Timeline card for selecting a date.

The parameters for Calendar are:

Name Type Default Values Description
title string - - the text you would like to appear in the Calendar
dateTime string - - timestamp of inital selected date
minDate string - - timestamp of lower limit of date range
maxDate string - - timestamp of upper limit of date range
stage string - start, confirmation render the date or time component individually
timeFormat string 24h - display time in 12 or 24 hour format
startDay string mon sat, sun, mon day that the week should start on
disabledDays comma separated string - mon, tues, weds, thurs, fri, sat, sun days of the week that should not be selectable
format string - ‘ddd D YYYY h’, ‘YY DD MM’,etc For full reference of the supported formats : https://day.js.org/docs/en/display/format

<TimelineMessage>
  <Calendar title="When would you like to set it?" dateTime="1562112000000" maxDate="1562457600000" minDate="1562112000000"/>
</TimelineMessage>

Calendar with Saturdays and Sundays disabled

<TimelineMessage>
  <Calendar title="When do you want this PTO to start?" disabledDays="sat,sun" />
</TimelineMessage>

Calendar with the week starting on Sunday

<TimelineMessage>
  <Calendar title="When would you like to set it?" startDay="sun" />
</TimelineMessage>

Card

A Card is a way of showing a single image

The parameters for Card are:

Name Type Default Values Description
title string - - the title text for the Card
imgUrl string - - the URL the image will be loaded from - 250x250px works best. If a videoUrl is provided the imgUrl will be used as the thumbnail image
videoUrl string - - the URL (youtube or vimeo) the video will be loaded from
imgData string - - A base64 encoded version of an image, if imgUrl is set this will not be used
alt string - - the text that describes the image

An example of Card Markup is:

<TimelineMessage>
  <Card title="Look at this" imgUrl="https://picsum.photos/250/250/?random&amp;g" alt="Lovely image" />
</TimelineMessage>

Cards can also be clickable

<TimelineMessage>
  <Card imgUrl="https://thenib.imgix.net/usq/1d97429f-4a64-4d52-bfdb-c36172c05228/this-is-not-fine-001-dae9d5.png" url="https://www.servisbot.com" alt="Hello" title="Check this out" selectable="true" linkOpenTarget="detail" />
</TimelineMessage>

To open in a new tab, just adjust linkOpenTarget="detail" to linkOpenTarget="tab" To move to a brand new page, just adjust linkOpenTarget="detail" to linkOpenTarget="self"

Selectable cards can have a chevron icon to indicate that they are clickable

<TimelineMessage>
  <Card imgUrl="https://thenib.imgix.net/usq/1d97429f-4a64-4d52-bfdb-c36172c05228/this-is-not-fine-001-dae9d5.png" url="https://www.servisbot.com" alt="Hello" title="Check this out" hasSelectableChevron="true" linkOpenTarget="detail" />
</TimelineMessage>

Card with video

<TimelineMessage>
    <Card videoUrl="https://youtu.be/TiYIR5eROOU" title="Check this out" />
</TimelineMessage>

Card with video and custom thumbnail

<TimelineMessage>
    <Card videoUrl="https://vimeo.com/326450452" imgUrl="https://bit.ly/2U1c08j" />
</TimelineMessage>

To make a large horizontal list (or carousel) with selectable options, the markup is:

  <TimelineMessage>
    <List title="Select a developer!" horizontal="true" selectable="true" style="large-icon">
      <Item title="Grumpy" subtitle="the dwarf" id="1" imageUrl="https://picsum.photos/200/150/?random&amp;a">
        <Option title="Select" id="Grumpy" />
        <Option title="See Profile" url="https://servisbot.com/about/" urlTitle="Profile"/>
      </Item>
      <Item title="Happy" subtitle="the dwarf" id="2" imageUrl="https://picsum.photos/200/150/?random&amp;b">
        <Option title="Select" id="Happy" />
        <Option title="See Profile" url="https://servisbot.com/about/" urlTitle="Profile"/>
      </Item>
      <Item title="Sleepy" subtitle="the dwarf" id="3" imageUrl="https://picsum.photos/200/150/?random&amp;c">
        <Option title="Select" id="Sleepy" />
        <Option title="See Profile" url="https://servisbot.com/about/" urlTitle="Profile"/>
      </Item>
      <Item title="Bashful" subtitle="the dwarf" id="4" imageUrl="https://picsum.photos/200/150/?random&amp;d">
        <Option title="Select" id="Bashful" />
        <Option title="See Profile" url="https://servisbot.com/about/" urlTitle="Profile"/>
      </Item>
      <Item title="Sneezy" subtitle="the dwarf" id="5" imageUrl="https://picsum.photos/200/150/?random&amp;e">
        <Option title="Select" id="Sneezy                      " />
        <Option title="See Profile" url="https://servisbot.com/about/" urlTitle="Profile"/>
      </Item>
    </List>
  </TimelineMessage>

To make a large horizontal list (or carousel) with no options, the markup is:

<TimelineMessage>
  <List selectable="true" horizontal="true" title="Who is your favourite dwarf?" style="large-icon">
    <Item id="0" title="Grumpy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;a" />
    <Item id="1" title="Happy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;b" />
    <Item id="2" title="Sleepy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;c" />
    <Item id="3" title="Bashful" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;d" />
    <Item id="4" title="Sneezy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;e" />
    <Item id="5" title="Dopey" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;f" />
    <Item id="6" title="Doc" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;g" />
  </List>
</TimelineMessage>

  <TimelineMessage>
    <List horizontal="true" title="Who is your favourite dwarf?" style="large-icon">
      <Item id="0" title="Grumpy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;a" />
      <Item id="1" title="Happy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;b" />
      <Item id="2" title="Sleepy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;c" />
      <Item id="3" title="Bashful" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;d" />
      <Item id="4" title="Sneezy" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;e" />
      <Item id="5" title="Dopey" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;f" />
      <Item id="6" title="Doc" subtitle="the dwarf" imageUrl="https://picsum.photos/200/150/?random&amp;g" />
    </List>
  </TimelineMessage>

  <TimelineMessage>
    <List horizontal="true" title="Who is your favourite dwarf?" style="large-icon">
      <Item id="0" imageUrl="https://picsum.photos/200/150/?random&amp;a" />
      <Item id="1" imageUrl="https://picsum.photos/200/150/?random&amp;b" />
      <Item id="2" imageUrl="https://picsum.photos/200/150/?random&amp;c" />
      <Item id="3" imageUrl="https://picsum.photos/200/150/?random&amp;d" />
      <Item id="4" imageUrl="https://picsum.photos/200/150/?random&amp;e" />
      <Item id="5" imageUrl="https://picsum.photos/200/150/?random&amp;f" />
      <Item id="6" imageUrl="https://picsum.photos/200/150/?random&amp;g" />
    </List>
  </TimelineMessage>

Its also possible to make images themselves clickable as part of a carousel too.

  <TimelineMessage>
   <List title="Select a clickable image!" horizontal="true" style="large-icon" selectable="true">
    <Item subtitle="Rogers" id="1" imageUrl="https://picsum.photos/200/150/?random&amp;a" url="http://servisbot.com" urlTitle="SERVISBOT" linkOpenTarget="self" />
    <Item subtitle="Casey" id="1" imageUrl="https://picsum.photos/200/150/?random&amp;a" url="http://servisbot.com" urlTitle="SERVISBOT" linkOpenTarget="tab" />
    <Item subtitle="Heung" id="2" imageUrl="https://picsum.photos/200/150/?random&amp;b" url="https://lovindublin.com/food" urlTitle="LOVIN FOOD" linkOpenTarget="messenger" />
    <Item subtitle="Rellis" id="3" imageUrl="https://picsum.photos/200/150/?random&amp;c" url="https://google.com" urlTitle="Google" linkOpenTarget="messenger" />
   </List>
  </TimelineMessage>

To make a small horizontal list (or carousel) the markup is:

  <TimelineMessage>
    <List selectable="true" title="Who is your favourite dwarf?" style="small-icon" horizontal="true">
      <Item id="0" title="Grumpy" imageUrl="https://picsum.photos/60/60/?random&amp;a" />
      <Item id="1" title="Happy" imageUrl="https://picsum.photos/60/60/?random&amp;b" />
      <Item id="2" title="Sleepy" imageUrl="https://picsum.photos/60/60/?random&amp;c" />
      <Item id="3" title="Bashful" imageUrl="https://picsum.photos/60/60/?random&amp;c" />
      <Item id="4" title="Sneezy" imageUrl="https://picsum.photos/60/60/?random&amp;d" />
      <Item id="5" title="Dopey" imageUrl="https://picsum.photos/60/60/?random&amp;e" />
      <Item id="6" title="Doc" imageUrl="https://picsum.photos/60/60/?random&amp;f" />
    </List>
  </TimelineMessage>

DateTime

Timeline card with two states for selecting a date + a time.

The parameters for DateTime are:

Name Type Default Values Description
format string - ‘ddd D YYYY h’, ‘YY DD MM’,etc For full reference of the supported formats : https://day.js.org/docs/en/display/format

If the available times will change based on what date is selected, its better to use the calendar card by itself first to get the day the user wants, then a BaaS, followed by a Dropdown Card with the available days.

DateTime with the date stage selected

<!-- Select date with calendar stage selected -->
 <TimelineMessage>
   <DateTime title="When would you like to set it?" stage="start" dateTime="1562112000000" maxDate="1562457600000" minDate="1562112000000" />
 </TimelineMessage>

DateTime on the time stage selected

<TimelineMessage>
  <DateTime title="When would you like to set it?" stage="confirmation" dateTime="1557246600000" timeFormat="12h"/>
</TimelineMessage>

Provide users with a dropdown with a list of options to choose from. Good for when there are more options available than will fit on a list component

Name Type Default Values Description
title string - - Text that is show in the dropdown
value string - - the default value seleced by the dropdown
description string - - the description that appears on the call to action
confirmButtonText string CONFIRM - Text that appears on the confirm button
id string - - Unique id for each drop down option
interactionType string utterance utterance, event
  • Event fires a markup interaction with the option selected
  • Utterance adds a message to the timeline with the option selected
<TimelineMessage>
  <Dropdown value="3" title="Select an appropriate option" description="When would you like to set it?" confirmButtonText="Select">
    <DropdownItem id="1" title="Option 1" />
    <DropdownItem id="2" title="Option 2" />
    <DropdownItem id="3" title="Option 3" />
  </Dropdown>
</TimelineMessage>

To use this markup with markup interactions

<TimelineMessage>
  <Dropdown value="3" description="When would you like to set it?" interactionType="event">
    <DropdownItem id="1" title="Option 1" />
    <DropdownItem id="2" title="Option 2" />
    <DropdownItem id="3" title="Option 3" />
  </Dropdown>
</TimelineMessage>

Time Select Cards

Card for selecting a time using the 12- or 24-hour format

<TimelineMessage>
   <Time title="When would you like to set it?" dateTime="1557246600000" timeFormat="12h"/>
</TimelineMessage>

List

  • A List is a simple list of things
  • The List can be simple text, pair text with icons or pair text with images
  • The List can also allow the user to select one of the list items

Images for large carousels should not be taller 230 X 150

The parameters for a List are:

Name Type Default Values Description
title string - - the title text for the list
style string standard standard, small-icon, large-icon the style of the list that you would like
selectable boolean false true, false whether the list items should selectable
type string chevron disc, ordered, unordered, chevron the type of the list that you would like
horizontal boolean false true, false whether the list displays as a horizontal scrollable list
preventRetries boolean false true, false whether the list should only be selectable once
interactionType string utterance utterance, event
  • Event fires a markup interaction with the option selected
  • Utterance adds a message to the timeline with the option selected

List with different types

The type property of the List element can be used to set the type of list to render. The chevron and disc properties are supported only on selectable lists and the ordered and unordered properties are supported on non-selectable lists.

<TimelineMessage>
<List type="disc" selectable="true" >
  <Item title="Item one" id="1"/>
  <Item title="Item two" id="2" />
  <Item title="Item three" id="3" />
</List>
</TimelineMessage>

Different List-Types

List with interactionType

These components can be be set to send an utterance (a message in the conversation) or an event (a message sent to the bot indicating some action). The following example shows a List which uses an event.

<TimelineMessage>
  <List title="Please select a number" selectable="true" interactionType="event">
     <Item title="Option one is here" id="1"/>
     <Item title="Option two is here" id="2"/>
     <Item title="Option three is here" id="3"/>
     <Item title="Option four is here" id="4"/>
  </List>
</TimelineMessage>

List with preventRetries

These components can be be set to only allow one selection

<TimelineMessage>
  <List title="Please select a number" selectable="true" preventRetries="true" interactionType="event">
     <Item title="Option one is here" id="1"/>
     <Item title="Option two is here" id="2"/>
     <Item title="Option three is here" id="3"/>
     <Item title="Option four is here" id="4"/>
  </List>
</TimelineMessage>

After the user selects an option - they the list will change state.

The List can look differently depending on the combination of parameters passed to it.

Vertical List, No Icons

To make a vertical list with no icons the markup is:

<TimelineMessage>
  <List selectable="true" title="Who is your favourite dwarf?" style="standard">
    <Item id="0" title="Grumpy" />
    <Item id="1" title="Happy" />
    <Item id="2" title="Sleepy" />
    <Item id="3" title="Bashful" />
    <Item id="4" title="Sneezy" />
    <Item id="5" title="Dopey" />
    <Item id="6" title="Doc" />
  </List>
</TimelineMessage>

Vertical List with Icons

The new parameters for a list item with an Icon are:

  • iconUrl (string) the url of an icon image
  • Small Icons: N x N px
  • Large Icons: N x N px

To make a vertical list with small inline icons the markup is:

<TimelineMessage>
  <List selectable="true" title="Who is your favourite dwarf?" style="small-icon">
    <Item id="0" title="Grumpy" iconUrl="https://imgplaceholder.com/18x18/ffffff/333333/fa-image" />
    <Item id="1" title="Happy" iconUrl="https://imgplaceholder.com/18x18/ffffff/333333/fa-globe" />
    <Item id="2" title="Sleepy" iconUrl="https://imgplaceholder.com/18x18/ffffff/333333/fa-book" />
    <Item id="3" title="Bashful" iconUrl="https://imgplaceholder.com/18x18/ffffff/333333/fa-car" />
    <Item id="4" title="Sneezy" iconUrl="https://imgplaceholder.com/18x18/ffffff/333333/fa-building" />
  </List>
</TimelineMessage>

To make a vertical list with large icons the markup is:

<TimelineMessage>
  <List selectable="true" title="Who is your favourite dwarf?" style="large-icon">
    <Item id="0" title="Grumpy" iconUrl="https://imgplaceholder.com/48x48/ffffff/333333/fa-image" />
    <Item id="1" title="Happy" iconUrl="https://imgplaceholder.com/48x48/ffffff/333333/fa-globe" />
    <Item id="2" title="Sleepy" iconUrl="https://imgplaceholder.com/48x48/ffffff/333333/fa-book" />
    <Item id="3" title="Bashful" iconUrl="https://imgplaceholder.com/48x48/ffffff/333333/fa-car" />
    <Item id="4" title="Sneezy" iconUrl="https://imgplaceholder.com/48x48/ffffff/333333/fa-building" />
  </List>
</TimelineMessage>

Item

  • An Item is contained in a list
  • Each Item corresponds to a single entry in a List
  • An item can have text with either an icon or an image
  • If an Item has option children and those Options have a “url” parameter, it will open that url in a new window in the messenger.

Images for small carousel should not be taller or wider than than 44px

The parameters for Item are:

Name Type Default Values Description
title string - - the text you would like to appear in the Item
subtitle string - - a subtitle that appears below the text on the when “horizontal=true” and “style=large-icon” on a List component
id string - - the identifier for this Item to be used in selection
iconUrl string - - the URL of the icon you want to appear with the Item when “horizontal=false”
imageUrl string - - the URL of the image you want to appear with the item when “horizontal=true”
url string - - a url that is loaded when an item is clicked
linkOpenTarget string - - open item url in a new tab tab, in webview messenger or change the current parent page self

An example of Item markup is:

<TimelineMessage>
  <List selectable="true" title="Who is your favourite dwarf?">
     <Item title="My item" id="item-1" iconUrl="https://picsum.photos/48/48/?random&amp;f" />
  </List>
</TimelineMessage>

See also: List

DetailView

A call to action that opens a web page in an iFrame

The parameters for DetailView are:

Name Type Default Values Description
url string - - the url you want to open in the webview
description string - - the description that appears on the call to action
title string - - the title that appears at the top of the webview
interactionType string - event event sends a markup interaction on close or complete
showBackButton string true true, false whether the back button should be shown

An example of DetailView markup is:

<TimelineMessage>
  <DetailView
    title="ServisBOT"
    description="Check out our bots"
    url="https://servisbot.com"
  />
</TimelineMessage>

Detail Views with User input

Detail views are sent as just messages by default. It is possible for detailviews to be expanded to take further input for filling slots (using SBIntents) or to wait for user input (using a markup interaction node in Classic Flow).

Specifiy interactionType=event in your DetailView markup:

<TimelineMessage>
  <DetailView
    title="ServisBOT"
    description="Check out our bots"
    url="https://servisbot.com"
    interactionType="event"
  />
</TimelineMessage>

The markup above will create two potential events depending on user interactions

  • Close when the user closes the detailview
  • Complete to register when the main task on a detail view page is complete.

    window.parent.parent.postMessage({
        type: "completeServisBotTask",
        closeOnComplete: true,
    }, 
    "https://mydomain.com"
    );
    

Additional data can also be sent from the detail view to the bot with the completion event.

To capture data on the completion of an action within a post message has to be sent to ServisBOT messenger from the iFramed page:

  • Data contained in a ‘message’ object will be sent along with the event to the bot.

The iFramed page should send a complete action post to its parent in the following format

 window.parent.parent.postMessage(
    {
      type: "completeServisBotTask",
        message: { itemSelected: 2 },
        closeOnComplete: true,
      },
      "https://mydomain.com"
    );
  }

Suggestion Prompt

A call to action that presents the user with suggested responses to a question

The SuggestionPrompt doesn’t take any parameters directly. It contains a list of options which have the suggested response set as the title parameter.

An example of SuggestionPrompt markup is:

<TimelineMessage>
  <SuggestionPrompt>
    <Option title="30 x 30" id="0" />
    <Option title="32 x 32" id="1" />
    <Option title="33 x 32" id="2" />
    <Option title="34 x 34" id="3" />
    <Option title="35 x 34" id="4" />
    <Option title="v36 x 36" id="5" />
    <Option title="v37 x 35" id="6" />
    <Option title="v38 x 36" id="7" />
  </SuggestionPrompt>
</TimelineMessage>

Map

  • A static Google Maps component
  • Plots a pin on the map based on coordinates
  • Requires a Google API key to be based into ServisBOT Messenger in the ServisBOT.init() function

We automatically provide a key for our testing and preview pages, but you will need to generate and maintain one when deploying your bot to production. You can obtain a key here: Google Maps API Key

The parameters for StaticMap are:

Name Type Default Values Description
description string - - the description to be associated with the map e.g. the address
lat string - - the latitude co-ordinate of the pin to place on the map
lng string - - the longitude co-ordinate of the pin to place on the map
googleApiKey string - - Optional field, if no key is provided in the ServisBOT config, a key can be provided in the timeline element

An example of StaticMap markup is:

<TimelineMessage>
  <StaticMap
    description="Heres the Aviva stadium"
    lat="53.335309"
    lng="-6.228413"
  />
</TimelineMessage>

Get Users Location Using a Map

The map timeline element can be used to request a users’s location simply by using it with the markup interaction node and adjusting the markup.

<TimelineMessage>
  <StaticMap
    title="Please confirm your location"
    interactionType="event"
  />
</TimelineMessage>

The results will be provided as part of msg.payload.markupInteraction.

"markupInteraction": {
  "lat": 42.34339322495768,
  "lng": -71.09655591550987
}

FileItem

  • A static component to preview files fetched from the url or download to user’s machine locally if file originates from the same domain.
  • Allows files from the same origin to be downloaded.
  • Allows showing previews of the files supported by respective browsers.
  • By default, files of type PDF, IMAGES(.img/.png/.jpeg) are shown in the preview. For not supported file types like xls,ppt the file will be automatically downloaded to the user’s machine.

Files are automatically rendered inside the browser if the browser can view those files. A file preview will only be shown of the file types which are supported by the browsers. To make the file downloadable, make sure it is from the same origin.

The parameters for FileItem are

Name Type Default Values Description
icon string ftblank ftblank, ftexcel, ftword, ftpdf the icon to display for the file type
url string - # the url of the file being downloaded/opened
alt string File to Download - the alternate text to display if your file is not rendered by the browser
title string Download File - the name of your file
linkOpenTarget string tab tab, download whether the file should be downloaded or opened in a new tab
showPreview boolean false true, false whether the file preview should be shown for the supported files. Files of type pdf, images are supported.
mimeType string - application/pdf, image/png, etc mimeType is needed to preview the file. A valid mimeType should be passed. Reference https://developer.mozilla.org/en-US/docs/Web/HTTP/Basics_of_HTTP/MIME_types/Complete_list_of_MIME_types

An example of FileItem markup is (with preview):

<TimelineMessage>
  <FileItem icon="ftpdf"
    url="https://servisbot.com/wp-content/uploads/2019/08/ServisBOT_AA_CaseStudy.pdf"
    alt="information file"
    title="Please download this file for more information."
    linkOpenTarget="download" showPreview="true"
    mimeType="application/pdf" />
</TimelineMessage>

An example of FileItem markup is (without preview):

<TimelineMessage>
  <FileItem icon="ftpdf"
    url="https://servisbot.com/wp-content/uploads/2019/08/ServisBOT_AA_CaseStudy.pdf"
    alt="information file"
    title="Please download this file for more information."
    linkOpenTarget="download"
    mimeType="application/pdf" />
</TimelineMessage>

FileUpload

The parameters for FileUpload are:

Name Type Default Values Description
promptText string - - the title shown on the FileUpload element
promptButtonText string - - the label for the file upload call to action
retryButtonText string - - the label for the file replace call to action
confirmationText string - - the label for the file confirmation call to action
confirmButtonText string - - the label for the flow completion call to action
persist boolean true true, false whether the uploaded file should be permanently stored, if set to false any files uploaded will be erased at a later stage

An example of FileUpload markup is:

<TimelineMessage>
  <FileUpload
    promptText="Could you post a picture of the other vehicle?"
    promptButtonText="Upload Picture" retryButtonText="Replace"
    confirmButtonText="Complete"
    confirmationText="All set!"
  >
    <UploadItem fileType="image/\*" name="vehicle"/>
  </FileUpload>
</TimelineMessage>

UploadItem

An UploadItem is contained in FileUpload Each UploadItem corresponds to a required file upload

The parameters for UploadItem are:

Name Type Default Values Description
label string - - the label for the UploadItem (not shown for single file uploads)
name string - - the identifier with which the file is associated
fileType mime type - - A mime type which lets indicate the kind of file you want uploaded
interactionType string utterance utterance, event
  • Event fires a markup interaction with the option selected
  • Utterance adds a message to the timeline with the option selected
<TimelineMessage>
  <FileUpload
    promptText="Could you provide photos of the front and back of your licence?"
    promptButtonText="Upload Pictures"
    retryButtonText="Replace"
    confirmationText="All set!"
    confirmButtonText="Complete">
      <UploadItem fileType="image/*" label="Front" name="LicenceFront"/>
      <UploadItem fileType="image/*" label="Back" name="LicenceBack"/>
    </FileUpload>
</TimelineMessage>

OptionCard

The parameters for OptionCard are:

Name Type Default Values Description
title string - - the title text for the option card
subtitle string - - the subtitle text for the option card
description string - - the description text for the option card
imgUrl string - - the URL the image will be loaded from
alt string - - the text that describes the image
preventRetries boolean false true, false whether the options should only be selectable once
<TimelineMessage>
  <OptionCard title="I found an existing order in your account" subtitle="GrabnGo Fresh" description="1 x Balsamic Salad, 1 Grilled Salmon Bowl, 2 X Falafel Wraps" alt="A nice food image" imgUrl="https://s3-us-west-2.amazonaws.com/lightstalking-assets/wp-content/uploads/2018/07/08175352/brooke-lark-229136-unsplash.jpg" preventRetries="true">
    <Option title="Track" id="Track" />
    <Option title="View Order Self" id="ViewOrderSelf" url="http://servisbot.com" urlTitle="SERVISBOT" linkOpenTarget="self" />
    <Option title="View Order Tab" id="ViewOrderTab" url="http://servisbot.com" urlTitle="SERVISBOT" linkOpenTarget="tab" />
    <Option title="View Order Messenger" id="ViewOrderMessenger" url="https://lovindublin.com/food" urlTitle="LOVIN FOOD" linkOpenTarget="messenger" />
  </OptionCard>
</TimelineMessage>

Star Rating Card

Name Type Default Values Description
title string - - the title text for the option card
maxValue string - 1-10 the number of options available to the user
preventRetries boolean false true, false whether the options should only be selectable once
<TimelineMessage>
  <StarRating
    title="Can you please rate our service today?"
    maxValue="5"
    preventRetries="true"
  />
</TimelineMessage>

TextMsg

  • A entry in the conversation for displaying text
  • It takes the text as a child of the component
  • It takes no parameters

An example of TextMsg markup is:

<TimelineMessage>
  <TextMsg>Hello there!</TextMsg>
  <TextMsg>Whats your name?</TextMsg>
</TimelineMessage>

Generated JSON object

The markupObject is being generated by the xml2js module. Given an XML that looks like this:

<TimelineMessage>
    <List style="icon" selectable="true">
    <Item id="SAVE" iconUrl="bank.ico" title="Savings Account" />
    <Item id="CREDIT" iconUrl="card.ico" title="Credit Account" />
    </List>
    <TextMsg>My 1st text message</TextMsg>
    <TextMsg>My 2nd text message</TextMsg>
</TimelineMessage>

The generated markupObject will look like this:

{
  "TimelineMessage": {
    "#name": "TimelineMessage",
    "children": [
      {
        "attributes": {
          "style": "icon",
          "selectable": "true"
        },
        "#name": "List",
        "children": [
          {
            "attributes": {
              "id": "SAVE",
              "iconUrl": "bank.ico",
              "title": "Savings Account"
            },
            "#name": "Item"
          },
          {
            "attributes": {
              "id": "CREDIT",
              "iconUrl": "card.ico",
              "title": "Credit Account"
            },
            "#name": "Item"
          }
        ],
      },
      {
        "content": "My 1st text message",
        "#name": "TextMsg"
      },
      {
        "content": "My 2nd text message",
        "#name": "TextMsg"
      }
    ],

  }