Timeline Markup

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

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.

An example of the TimelineMessage element is:

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

Table of Contents

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 TimelineMessage element is:

<TimelineMessage minimumDisplayTime="1.5">
  <TextMsg>Hello</TextMsg>
</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>

ButtonPrompt

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

One, or More than Three Options - Single Column

<TimelineMessage>
  <ButtonPromptContainer>
    <ButtonPrompt label="Option One"/>
    <ButtonPrompt label="Option Two"/>
    <ButtonPrompt label="Option Three"/>
  </ButtonPromptContainer>
</TimelineMessage>

Two Options - Side by side.

<TimelineMessage>
  <ButtonPromptContainer>
    <ButtonPrompt label="Option One"/>
    <ButtonPrompt label="Option Two"/>
  </ButtonPromptContainer>
</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
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" description="When would you like to set it?">
    <DropdownItem id="1" title="Option 1" />
    <DropdownItem id="2" title="Option 2" />
    <DropdownItem id="3" title="Option 3" />
  </Dropdown>
</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

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

DateTime

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

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="1557246600000" 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>

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
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 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">
     <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>

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>

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

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

Broadcast

Dismissable 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>

Option

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

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>

See also: BroadcastMsg, SuggestionPrompt, 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

An example of DetailView markup is:

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

SuggestionPrompt

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="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>

StaticMap

  • 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

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

An example of StaticMap markup is:

<TimelineMessage>
  <StaticMap
    description="Heres the Aviva stadium"
    lat="53.335309"
    lng="-6.228413"
  />
</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

It is also possible tp upload more than one image through the element.

<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

[](images/optioncard.png)

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>

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"
      }
    ],

  }