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
  • Detail View
  • Dropdowns
  • File Uploads
  • Lists (Selectable)
  • Maps (Get User’s Location)

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 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 Detail View using Markup interactions

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

Example Map using Markup interactions

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

Timeline Elements

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

One Column Default Display

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

Two Column Display

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

#### Inline Flowed Display

  <TimelineMessage>
    <ButtonPromptContainer display="inline">
      <ButtonPrompt label="Option One"/>
      <ButtonPrompt label="Option Two"/>
      <ButtonPrompt label="Three"/>
      <ButtonPrompt label="Option Four"/>
      <ButtonPrompt label="Option Five"/>
      <ButtonPrompt label="Option Six"/>
    </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 |

  <TimelineMessage>
    <Calendar title="When would you like to set it?" dateTime="1562112000000" maxDate="1562457600000" minDate="1562112000000"/>
  </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 | | 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>

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.

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

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

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

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

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

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 it’s parent in the following format

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

To close the detailview automatically when the action is complete you can pass closeOnComplete: true when posting the message to the parent. Like this: * Specifiy interactionType=event in your DetailView markup:

    <TimelineMessage>
      <DetailView
        title="Form"
        description="Fill out this form please"
        url="https://myform.com"
        interactionType="event"
      />
    </TimelineMessage>

If you would like the iframe to close when the action is complete you can pass closeOnComplete: true when you are posting the message to the parent. Like this:

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

=======

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>

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
}

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

[](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>

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

  }