Formatting

Learn how to format the values of entities stored in the bot memory.

When displaying values of entities stored in Bot Memory, you can use Handlebars templates for some common formatting needs - dates, currencies etc.

You can also use the Handlebars formatters to perform advanced transformations like forEach statements for displaying arrays of values.

Displaying Entity Values

Each entity value stored in the short-term memory can be accessed by it’s name:

{{entityName}}

For example:

{{doctor}} is not available on {{date}}.

Will be displayed as: “Dr. John Burke is not available on 11 Feb.”

Displaying Rich Text

You can display rich text in Facebook Messenger, Viber and the Web widget. What format is supported depends on the native rendering support of the specific channel.

Facebook Messenger

Facebook Messenger offers limited MarkDown-like formatting capabilities:

"type": "message",
"messages": [
  [
    "Facebook supports _Italic_",
    "Facebook supports *Bold*",
    "Facebook supports ~Strikethrough~",
    "Facebook supports 'Monospace'",
    "Facebook supports ```Codeblock```"
  ]
]

For details, see the official Facebook help center article.

Viber

Viber offers limited support for HTML tags:

"type": "message",
"messages": [
  [
    "Viber supports <i>Italic</i>",
    "Viber supports <b>Bold</b>",
    "Viber supports <s>Strikethrough</s>",
    "Viber supports <font size='30'>big</font> font",
    "Viber supports <font color='#7F00FF'>colored</font> text"
  ]
]

For details, see the official Viber documentation article.

Web

The Web widget supports MarkDown and HTML:

"type": "message",
"messages": [
  [
    "the Web widget supports _Italic_",
    "the Web widget supports **Bold**",
    "the Web widget supports ~~Strikethrough~~",
    "the Web widget supports `Code`",
    "the Web widget supports typographic symbols (c) (C) (r) (R) (tm) (TM) (p) (P) +-",
    "# the Web widget supports Headings",
    "> the Web widget supports block quotes",
    "the Web widget supports lists\n* item1\n* item2\n  * subitem 1 (idented by 2 spaces!)",
    "the Web widget supports ordered lists\n1. item1\n2. item2\n  a. subitem 1 (idented by 2 spaces!)",
    "the Web widget supports tables\n| Option | Description |\n| ------ | ----------- |\n| data   | vaue",
    "the Web widget supports hyperlinks [NativeChat Portal](https://bots.nativechat.com 'title for this link')",
    "the Web widget supports raw links https://bots.nativechat.com",
    "the Web widget supports embedded images ![Stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg 'The Stormtroopocat')",
    "the Web widget supports <i>HTML Italic</i>",
    "the Web widget supports <b>HTML Bold</b>",
    "the Web widget supports <s>HTML Strikethrough</s>",
    "the Web widget supports <font size='30'>big</font> font",
    "the Web widget supports <font color='#7F00FF'>colored</font> text",
    "the Web widget supports HTML embedded images <img src='https://octodex.github.com/images/stormtroopocat.jpg' alt='The Stormtroopocat' title='The Stormtroopocat' height='40px'/>",
    "the Web widget supports HTML ordered lists <ol><li>First item</li><li>Second item</li></ol>",
    "the Web widget supports HTML unordered lists <ul><li>one</li><li>two</li></ul>",
    "the Web widget supports <a href=\"mailto:someone@example.com\">Send email</a>",
    "the Web widget supports <a href=\"tel:5554280940\">Call us at 555-428-0940</a>"
  ]
]

MS Teams

Microsoft Teams supports MarkDown and HTML:

"type": "message",
"messages": [
  [
    "MS Teams supports _Italic_",
    "MS Teams supports **Bold**",
    "MS Teams supports `Inline Code`",
    "MS Teams supports\n```\nMultiline\ncode\nblocks\n```",
    "# MS Teams supports Headings",
    "> MS Teams supports block quotes",
    "MS Teams supports lists\n* item1\n* item2\n  * subitem 1 (idented by 2 spaces!)\n    * sub-sub-item 1 (4 spaces)",
    "MS Teams supports flat ordered lists\n1. item1\n1. item2\n1. item3",
    "MS Teams supports hyperlinks [NativeChat Portal](https://bots.nativechat.com 'title for this link')",
    "MS Teams supports embedded images ![Stormtroopocat](https://octodex.github.com/images/stormtroopocat.jpg 'The Stormtroopocat')",
    "MS Teams supports <i>HTML Italic</i>",
    "MS Teams supports <b>HTML Bold</b>",
    "MS Teams supports <s>HTML Strikethrough</s>",
    "MS Teams supports <font size='30'>big</font> font",
    "MS Teams supports <font color='#7F00FF'>colored</font> text",
    "MS Teams supports HTML embedded images <img src='https://octodex.github.com/images/stormtroopocat.jpg' alt='The Stormtroopocat' title='The Stormtroopocat'/>",
    "MS Teams supports HTML ordered lists <ol><li>First item</li><li>Second item</li></ol>",
    "MS Teams supports HTML unordered lists <ul><li>one</li><li>two</li></ul>",
    "MS Teams supports <a href=\"mailto:someone@example.com\">Send email</a>",
  ]

For more details please refer to the official documentation.

Displaying Emojis

You can display various emojis by copying and pasting the pictures inside your cognitive flow (for example, in messages or quick replies) or inside answers in the question answering section (for example, the “small talk” category). A full list of the supported emojis and a good source for copying them is available at https://unicode.org/emoji/charts/full-emoji-list.html.

"type": "message",
"messages": [
  [
    "Did you find the provided information helpful? 🙂"
  ]
],
"display": {
  "type": "quick-reply",
  "data": [
    "👍",
    "👎"
  ]
}

Formatting

It’s often that the entities that will be stored in a conversation might have properties that need to be formatted. For example, invoking an entity that has a date property will be displayed as a raw string Fri Aug 12 1987 00:00:00 GMT-0700 (Pacific Daylight Time) instead of a simple format such as August 12, 1987.

{{birthday}} <!-- output: Fri Aug 12 1987 00:00:00 GMT-0700 (Pacific Daylight Time) -->

To make it easy to format values in the memory, you have a set of built-in formatters that will save you time display the data in the format you want.

{{$date birthday}} <!-- output: Aug 12, 1987 -->

All formatters are prefixed with $ except for the block formatters like #forEach which are prefixed with # and have a closing tag. Block formatters wrap a part of the template to use it in a custom way.

    base template {{#blockFormatter}}child template{{/blockFormatter}}

Here is a list of the built-in formatters that you can directly use with every expression statement.

Date

You can format a date with either a shortcut built-in $date formatters that we have listed below, or use a custom formatting string.

     {{$date birthday}}               <!-- output is 'Jun 15, 2015' -->
     {{$date birthday 'medium'}}      <!-- output is 'Jun 15, 2015, 9:43:11 PM' -->
     {{$date birthday 'shortTime'}}   <!-- output is '9:43 PM' -->
     {{$date birthday 'mm:ss'}}       <!-- output is '43:11' -->

In case you have separate entities for date and time, which are of types Date and Time respectively, you can format them the following way. Note that the format parameter at the end cannot be omitted in this case.

    <!-- output is 'Jun 15, 2015, 9:43:11 PM' -->
    {{$date date time 'medium'}}

• 'medium' - equivalent to 'll[,] LTS' (e.g. Sep 3, 2010, 12:05:08 PM for en-US)
• 'short' - equivalent to 'L[,] LT' (e.g. 9/3/2010, 12:05 PM for en-US)
• 'fullDate' - equivalent to 'dddd[,] LL' (e.g. Friday, September 3, 2010 for en-US)
• 'longDate' - equivalent to 'LL' (e.g. September 3, 2010 for en-US)
• 'mediumDate' - equivalent to 'll' (e.g. Sep 3, 2010 for en-US)
• 'shortDate' - equivalent to 'L' (e.g. 9/3/2010 for en-US)
• 'mediumTime' - equivalent to 'LTS' (e.g. 12:05:08 PM for en-US)
• 'shortTime' - equivalent to 'LT' (e.g. 12:05 PM for en-US)
• 'fromNow' - relative time from now formatted as literal expression. Dates in the past will be shown as 3 minutes ago, 11 hours ago, 5 years ago and dates in the future will be shown as in 4 minutes, in 1 hour, in 2 days etc.

NativeChat is using moment.js to format the dates. You can see the full explanation of the formatting strings here.

Dates and timezones

Dates are formatted using the bot’s or user’s timezone. For the examples, assume that the timezone is ‘America/New_York (GMT-05:00)’ and the format is ‘YYYY-MM-DD HH:mm ZZ’.

If the date contains timezone then it’s converted to the bot’s/user’s timezone.

If the date has no timezone then the bot’s/user’s timezone is set for the date, but it’s not converted.

In case you still need to convert the date in a specific time zone you can use an additional parameter:

    <!-- date = '2017-10-12', time = '15:30', timezone = 'America/New_York' -->
    {{$date date time 'medium' 'UTC'}} <!-- output is 'Dec 10, 2017, 20:30:00 PM' -->

Currency

You can format a number as currency by using the $currency formatter in every expression statement by passing an ISO 4217 currency code such as 'USD'. You can also control the number of digits and the usage of symbol ($) or currency code (USD) as a suffix of the value.

     {{amount}}                             <!-- 2230.30 -->
     {{$currency amount 'USD'}}             <!-- $2,230.30 -->
     {{$currency amount 'USD' precision=0}} <!-- $2,230 -->

Here is the full set of parameters that you can use when formatting currency:

• locale - a culture-specific locale e.g. 'en-US'
• precision - number of decimal digits e.g. 2

Percent

You can format a number as percent by using the $percent formatter. You also have the option to pass the number of decimal digits as an integer.

     {{amount}}            <!-- 0.3245 -->
     {{$percent amount}}   <!-- 32.45% -->
     {{$percent amount 4}} <!-- 32.4500% -->

Number

You can format a number as text by configuring locale, precision, decimal and thousand separators.

     {{amount}}                                   <!-- 2230.30 -->
     {{$number amount precision=0}}               <!-- 2230 -->
     {{$number amount precision=0 thousand=','}}  <!-- 2,230 -->

Here is the full set of parameters that you can use when formatting a number:

• locale - a culture-specific locale e.g. 'en-US'
• decimal - a decimal separator '.'
• thousand - a thousand separator - ','
• precision - number of decimal digits e.g. 2

UpperCase

You can format a string to upper case using the $uppercase formatter.

     {{title}}             <!-- 'This is my title' -->
     {{$uppercase title}}  <!-- 'THIS IS MY TITLE' -->

LowerCase

You can format a string to lower case using the $lowercase formatter.

     {{title}}             <!-- 'This is my title' -->
     {{$lowercase title}}  <!-- 'this is my title' -->

Capitalize

You can capitalize the first word of a sentence using the $capitalize formatter.

     {{title}}              <!-- 'this is my title' -->
     {{$capitalize title}}  <!-- 'This is my title' -->

CapitalizeAll

You can capitalize all words of a sentence using the $capitalizeAll formatter.

     {{title}}                 <!-- 'this is my title' -->
     {{$capitalizeAll title}}  <!-- 'This Is My Title' -->

EncodeURI

You can encode a string as a URI component to use in a URI using the $encodeURI formatter.

    {{search}}                                  <!-- 'The Great Gatsby' -->
    https://book.shop/?q={{$encodeURI search}}  <!-- 'https://book.shop/?q=The%20Great%20Gatsby' -->

JSON

You can serialize an object as JSON string using the $json formatter.

    {{location}}        <!-- '[object Object]' -->
     {{$json location}}  <!-- '{"latitude":42.650615,"longitude":23.379194}'

forEach, each, if-else, unless

You can iterate over each item in an array using the #forEach block formatter.

    <!-- '["John", "Maria", "Robert", "Anna"]' -->
    {{$json friends}}

    <!-- 'Hello, John! Hello, Maria! Hello, Robert! Hello, Anna! ' -->
    {{#forEach friends}}Hello, {{item}}! {{/forEach}}

Let’s take an example with the following data:

"team": {
  "type": "goal",
  "steps": [
    {
      "type": "command",
      "command": "set-entity",
      "entity": "people",
      "data": [
        {
          "name": "Alex",
          "title": "Developer"
        },
        {
          "name": "Nick",
          "title": "Developer"
        },
        {
          "name": "George",
          "title": "Designer"
        },
        {
          "name": "Sundar",
          "title": "Manager"
        }
      ]
    }
  ]
}

Then in a message step you can use that data and format it using Handlebars built-in helpers:

if

    {
      "type": "message",
      "messages": [
        [
          "{{#each people}} {{#if ($eq this.title \"designer\")}}{{this.name}} is the best!{{/if}}{{/each}}",
        ]
      ]
    }

if-else

    {
      "type": "message",
      "messages": [
        [
          "{{#each people}} {{#if ($eq this.title \"manager\")}}Hello {{this.name}}, oh almighty!{{else}}Hello {{this.name}}, you puny {{this.title}}.{{/if}} {{/each}}",
        ]
      ]
    }

unless

You can use the unless helper as the inverse of the if helper. Its block will be rendered if the expression returns a falsy value.

    {
      "type": "message",
      "messages": [
        [
          "{{#each people}} {{#unless ($eq this.title \"designer\")}}{{this.name}} is the best!{{/unless}}{{/each}}",
        ]
      ]
    }

lookup

The lookup helper allows for dynamic parameter resolution using Handlebars variables.

This is useful for resolving values for array indexes.

    {
      "type": "message",
      "messages": [
        [
          "The name of the person at position 1 is {{lookup (lookup people 1) 'name'}}.",
        ]
      ]
    }

concat

Use $concat formatter to join values of multiple entities into a single string for use in the Cognitive Flow.

    <!-- 'Date: 2017.10.10 Time: 10:00' -->
    {{$concat 'Date: ' date ' Time: ' time}}