QuickBooks Digital Assistant

Digital Assistant with pre-built skills.

IBM Watson Web Chat

Enterprise-grade interface for IBM Watson

SAP Virtual Assistant

Reduce the SAP Support Cost

White Label Conversational AI

All-in-one conversational platform

Skills Store Platform About Blog Documentation Team Contact Us Watch demo
Get Started

JSON Format

Text

To display the text component inside the chat, please use the next example and parameters.

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "text",
      "value": "Hey Andrii"
    }]
  }
}

Available properties

Property Type Description Default
value string | string[] output message text -
size string container width sm | md | lg | xl | 2xl | full sm

Random Text

To use the random text component, please use the next specification.

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "randomText",
      "value": [
        "Hi",
        "Hey",
        "Hello"
      ]
    }]
  }
}

Available properties

Property Type Description Default
value string[] output message text -
size string container width sm | md | lg | xl | 2xl | full sm

Quick Reply

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "quickReply",
      "value": [
        "Yes",
        "No"
      ]
    }]
  }
}

Available properties

Property Type Description Default
value string[] output message text -
size string container width sm | md | lg | xl | 2xl | full sm

HTML

Html type is really helpful if you would like to build your custom message output format.

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "html",
      "value": "<span style=\"color:red;\">red text with a <b>bold</b> word</span>"
    }]
  }
}

make sure that your HTML string use escaped double quotes

refer to online JSON formatter to prepare your HTML string for JSON

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full sm
value string html string -

Image

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "image",
      "url": "https://cdn.hala.ai/web/main_business.png",
      "size": "lg"
    }]
  }
}

Available properties

Property Type Description Default
url string image source URL -
size string container width sm | md | lg | xl | 2xl | full sm

Video

We are using react-player an open-source component for playing a variety of URLs, including file paths, YouTube, Facebook, Twitch, SoundCloud, Streamable, Vimeo, Wistia, Mixcloud, DailyMotion and Kaltura.

Refer to react-player for additional details and optional configuration properties

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "video",
      "url": "https://youtu.be/cCPlACUnO6U",
      "size": "md",
      "options": {
        "playing": true
      }
    }]
  }
}

Available properties

Property Type Description Default
url string | string[] video source URL -
size string container width sm | md | lg | xl | 2xl | full sm
options object to set options property, refer to react-player Props section -

Button

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "button",
      "props": {
          "label": "Open link",
          "primary": true,
          "link": "https://hala.ai",
          "icon": "o-arrow-circle-right"
      }
    }]
  }
}

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full sm
props object button properties, refer below -

Button props properties

Property Type Description Default
label string button text content -
color string button color base | primary | secondary | red | redLight | dark base
size string button size xs | 2xs | base | lg | 2lg base
link string URL of the page the link goes to -
icon string to set icon name, refer to Heroicons, use prefixes
o-{icon-name} for outline, s-{icon-name} for solid		 -
loading boolean loading icon indicator false
disabled boolean a disabled button is unusable and un-clickable false

Grid

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "grid",
      "cols": 3,
      "rows": 3,
      "gap": 3,
      "items": [{
        "row": 3,
        "col": 2,
        "items": [{
          "type": "text",
          "value": "Section 1"
        }]
      },{
        "items": [{
          "type": "text",
          "value": "Section 2"
        }]
      },{
        "row": 2,
        "items": [{
          "type": "text",
          "value": "Section 3"
        }]
      }]
    }]
  }
}

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full full
cols number number of equally sized columns, 1 - 12 3
rows number number of equally sized rows, 1 - 6 3
gap string padding between both rows and columns, 0 | 0.5 | 1 | 2 | 3 | 4 | 3
items object[] an array of GridSection items -

GridSection properties

Property Type Description Default
col string make a section span {n} columns, 1 - 12 | full 1
row string make a section span {n} rows, 1 - 6 | full 1
padding string padding for section content, 0 | 0.5 | 1 | 2 | 3 | 4 | 2
items object[] an array of message output, can be any type that is presented on that page.
example above		 -

Heading Section

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "SectionHeading",
      "props": {
        "heading": "Heading text", 
        "description": "Description text",
        "hr": true     
      }
    }]
  }
}

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full sm
props object SectionHeading properties, refer below -

SectionHeading props properties

Property Type Description Default
heading string heading text string -
description string description text string -
hr boolean shows a horizontal line at the bottom false
center boolean applies layout with aligned text by center false

Table

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "table",
      "canExport": true,
      "columns": [{
        "Header": "Date",
        "accessor": "date",
        "renderer": {
          "type": "date",
          "props": {
            "format": "LL"
          }
        }
      },{
        "Header": "Employee",
        "accessor": "firstName",
        "renderer": {
          "type": "html",
          "tpl": "{{row.original.firstName}} {{row.original.lastName}}"
        }
      },{
        "Header": "Duration",
        "accessor": "time_spent"
      },{
        "Header": "Amount",
        "accessor": "amount",
        "renderer": {
          "type": "currency",
          "currency": "$"
        }
      }],
      "data": [{
        "date": "2021-02-17",
        "firstName": "Andrey",
        "lastName": "Rudchuk",
        "time_spent": "01:30",
        "amount": "30"
      },{
        "date": "2021-02-18",
        "firstName": "Andrey",
        "lastName": "Rudchuk",
        "time_spent": "03:00",
        "amount": "60"
      }]
    }]
  }
}

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full xl
canExport boolean displays export button, triggered transform table data to .csv file to download false
fileName string name of .csv file to export, if canExport = true exported_data
data object[] The data array that you want to display on the table -
columns object[] an array of ColumnSchema items -
hiddenColumns string[] If a column accessor is contained in this array, it will be hidden, displays additional Details column, that triggers the left sidebar for a detailed view of a row data -
sorting boolean enable row sorting, and display sort indicator for each column false
uiStyle string set preconfigured table style:
  • panelList - make the table looks like a list, useful for tables inside a Grid
  • more types coming soon...
 -

ColumnSchema properties

Property Type Description Default
Header string column name that will be displayed in a table -
Footer string column footer name that will be displayed at the bottom of the table -
total boolean if true, it will summarize all row values for that column and that value will be displayed in the footer for that column false
accessor string the column's value will be looked upon the original row via that key, eg. If your column's accessor is firstName then its value would be read from row['firstName']. You can also specify deeply nested values with accessors like info.hobbies or even address[0].street -
renderer object object with configuration properties that used for formatting the column value -
renderer.type string type name for formatting the column value, available types:
date | percent | number | currency | file | link | html		 -

date column type

In the example below, we are setting formatting for the date column, so the date value 2021-02-17 from the data source will be displayed in the table as February 17, 2021

For date formatting we are using moment.js, to see available values for format property go to moment.js Format section

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Date",
          "accessor": "date",
          "renderer": {
            "type": "date",
            "props": {
              "format": "LL"
            }
          }
        },
        ...
      ],
      "data": [
        {
          "date": "2021-02-17",
          ...
        },
        ...
      ]
    }]
  }
}

percent column type

In the example below, we are setting formatting for the Percentage column, value 98 from the data source will be displayed in the table as 98%

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Percentage",
          "accessor": "value",
          "renderer": {
            "type": "percent"
          }
        },
        ...
      ],
      "data": [
        {
          "value": "98",
          ...
        },
        ...
      ]
    }]
  }
}

number column type

The type number helpful for transforming long numbers. In the example below, the amount value 20330.21312112 from the data source will be displayed in the table as 20,330.21

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Amount",
          "accessor": "amount",
          "renderer": {
            "type": "number"
          }
        },
        ...
      ],
      "data": [
        {
          "amount": "20330.21312112",
          ...
        },
        ...
      ]
    }]
  }
}

currency column type

In the example below, the amount value 330.21312112 from the data source will be displayed in the table as $330.21

Provide currency code for currency property

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Amount",
          "accessor": "amount",
          "renderer": {
            "type": "currency",
            "currency": "USD"
          }
        },
        ...
      ],
      "data": [
        {
          "amount": "330.21312112",
          ...
        },
        ...
      ]
    }]
  }
}

link column type

In the example below, each row in the Invoice column will be generated a hyperlink to the invoice_link destination

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Invoice",
          "accessor": "invoice_link",
          "renderer": {
            "type": "link",
            "props": {
              "label": "Download"
            }
          }
        },
        ...
      ],
      "data": [
        {
          "invoice_link": "https://hala.ai/",
          ...
        },
        ...
      ]
    }]
  }
}

html column type

In the example below, we have 2 properties firstName & lastName but we want to show them as a single column. We can use html type and provide a custom template to render data cells.

In your custom template, you can access the data source via {{row.original.['rowProperty']}}.

Refer to the HTML section to check how to prepare your HTML string for JSON

Example

{
  "output": {
    "hala": [{
      "type": "table",
      "columns": [
        {
          "Header": "Employee",
          "accessor": "firstName",
          "renderer": {
            "type": "html",
            "tpl": "<span style=\"color: red;\">{{row.original.firstName}} {{row.original.lastName}}</span>"
          }
        },
        ...
      ],
      "data": [
        {
          "firstName": "Andrey",
          "lastName": "Rudchuk"
          ...
        },
        ...
      ]
    }]
  }
}

Form

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "form",
      "formData":[{
        "type": "text",
        "name": "firstName",
        "label": "First name",
        "description": "Provide your first name"
      },{
        "type": "select",
        "name": "company",
        "label": "Company name",
        "creatable": true,
        "options": ["SpaceX", "Hala", "Nasa", "Amazon", "Netflix"]
      }]
    }]
  }
}

Available properties

Property Type Description Default
size string container width sm | md | lg | xl | 2xl | full full
formData object[] an array of FormItem -

FormItem properties

Property Type Description Default
type string form item type, available types:
text | email | password | number | hidden | tags | longText | date | radio | toggle | checkbox | select | condition | table | detailedAddress | section | title | header | hr		 -
label string field label -
description string field description -
name string unique field name (can not start with a number or use number as the key name). Field name also supports dot and bracket syntax, which allows you to easily create nested form fields. -
value any the default value for a field -
placeholder string text that appears in the form control when it has no value set -
col number if the item inside the Form section, sets a field section span {n} columns, 1 - 12 6
validationOptions object validation options and error message -
validationOptions.required string the field is required, and the value of the required property it's a string to return an error message -

text Field

A single-line text field. Line-breaks are automatically removed from the input value.

email Field

A field for editing an email address. Looks like a text input, but has validation parameters and relevant keyboard in supporting browsers and devices with dynamic keyboards.

password field

A single-line text field whose value is obscured. Will alert user if site is not secure.

number field

A control for entering a number. Displays a spinner and adds default validation when supported. Displays a numeric keypad in some devices with dynamic keypads.

hidden field

A control that is not displayed but whose value is submitted to the server.

longText field

Represents a multi-line plain-text editing control, useful when you want to allow users to enter a sizeable amount of free-form text, for example a comment on a review or feedback form.

Additional properties for longText field

Property Type Description Default
autoSize object Height auto-size feature can be set to an object
{ minRows: 1, maxRows: 3 }		 { minRows: 3, maxRows: 6 }

The rest of the properties of longText are the same as the original textarea.

tags field

A field for editing tags, keywords, etc

Additional properties for tags field

Property Type Description Default
value string[] the default value for a field -

date field

A control for entering a date (year, month, and day, with no time). Opens a date picker or numeric wheels for year, month, day when active in supporting browsers.

Additional properties for date field

Property Type Description Default
format string date format, to see available values go to moment.js format section -

radio field

A control that let a user select only one of a limited number of choices

Additional properties for radio field

Property Type Description Default
options string[] | object[] An array of values. Examples:
["Yes","No"]
[{
    "label": "Yes",
    "description": "yes, I want delivery"
},{
    "label": "No",
    "description": "no, I pick it up by my self"
}]		 -

checkbox field

Checkbox rendered by default as boxes that are checked (ticked) when activated. A checkbox allows you to select single values for submission in a form (or not).

toggle field

Has the same behavior as the checkbox, but with a different view

select field

Represents a control that provides a menu of options

Additional properties for select field

Property Type Description Default
options string[] | object[] An array of values. Examples:
["Apples", "Bananas"]
[{
    "label": "Apples",
    "value": "applesId"
},{
    "label": "Bananas",
    "value": "bananasId"
}]		 -
creatable boolean if true, gives the possibility to create custom value, if it's doesn't exist in the values list false
remote object gives the possibility to fetch data from Hala action or custom action, and transform the response to select field values -
remote.action string action_id - you can find that value on the Hala action page -
remote.parameters object the action parameters, Example:
{"companyId":"{{context.companyId}}"}		 -
optionsFormat object gives the possibility to transform data to select field values format -
optionsFormat.name string predefined options for select field:
  • countries - countries list
  • icons - icons list
 -
optionsFormat.path string if you are using a remote source, and your options array is nested deeply in response, you can specify a path to that array. Example: response.customer.invoices -
optionsFormat.item object if you are using a remote source, you can map your response to the option item. Let's say we fetch users list so to render the select field we need to map the option:
{"value": "userId", "label": "userName"}		 -
fetchOnInit boolean if the select field is remote, by default - values will be fetched when the user clicks on the select field, if true - values will be fetched immediately when the field is rendered false

table field

Represents a control that provides creating or editing table data.

Additional properties for table field

Property Type Description Default
columns object[] an array of ColumnSchema items -
canEditRow boolean if true - enable row editing false
canAddRow boolean if true - enable row adding false
rowSelection boolean if true - enable row select, can't work together with canEditRow or canAddRow false
itemForm object[] an array of FormItem. Required if canEditRow = true or canAddRow = true. Describes form schema for table row, where data key is equal to FormItem name property -
data object[] Required if rowSelection = true. Table data array which will transform to table rows for selection, all selected rows for submission in a form. -
value object[] if canEditRow = true or canAddRow = true, represent a table data array which will transform to table rows for editing and submission in a form. -

condition field

Creates a conditional rendering of form items

Example:

{
  "output": {
    "hala": [{
      "type": "form",
      "formData":[{
        "type": "radio",
        "name": "delivery",
        "label": "Delivery preferences",
        "options": [{
          "label": "Yes",
          "description": "yes, I want delivery"
        },{
          "label": "No",
          "description": "no, I pick it up by my self"
        }]
      },{
        "type": "condition",
        "values": {
          "delivery": "Yes"
        },
        "items": [{
          "type": "detailedAddress",
          "name": "address",
          "label": "Address",
          "description": "provide your delivery address"
        }]
      }]
    }]
  }
}

if delivery = Yes, then the new form element Address will show up

Additional properties for condition field

Property Type Description Default
items object[] an array of FormItem -
values object represent an object with "key": "value" that should exist in the form result - to render items -

detailedAddress field

Represents a predefined form section with such fields: country, address1, address2, zipCode, city, region

section

Form section gives the possibility to design form layout, you can use grid property to create columns for form fields, it will make your form more user friendly

Additional properties for section field

Property Type Description Default
items object[] an array of FormItem -
grid number number of equally sized columns, 1 - 12 -
size string container width sm | md | lg | xl | 2xl | full sm

header section

Represents as the form title or subject

Additional properties for header field

Property Type Description Default
title string title text -
description string description text -
border boolean if 'true' - displays a borderline on the bottom false

title section

Represents as the section title

Additional properties for title field

Property Type Description Default
title string title text -
description string description text -
size string container width sm | md | lg | xl | 2xl | 3xl | full 3xl

hr horizontal line

The horizontal line that can be used as a sections separator

Compare Section

Component for summary data comparison, useful for heading section of charts or tables

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "CompareStats",
      "title": "Revenue",
      "description": "compare to the previous month",
      "to": "11600",
      "from": "10800",
      "currency": "EUR"
    }]
  }
}

Available properties

Property Type Description Default
title string short title text -
description string description text -
to number current summary total to compare -
from number previous summary total to compare with -
currency string currency code, USD | EUR etc. -
center boolean if true, makes a section content centered false
shortNumbers boolean if true, converting big numbers to shorter, like 5000 to 5k false
small boolean if true, makes a section smaller false

Description List

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "DescriptionList",
      "title": "Cool Cars",
      "description": "Customer details",
      "values": {
        "Display Name": "Cool Cars",
        "Given Name": "Grace",
        "Family Name": "Pariente",
        "Email": "Cool_Cars@email.com",
        "City": "Half Moon Bay"
      }
    }]
  }
}

Available properties

Property Type Description Default
title string section title -
description string section description -
values object A data object that represents information to display -
uiType string view type, striped | inline | column -
py number control the vertical padding of a row element 5
size string container width sm | md | lg | xl | 2xl | full sm

Bar Chart

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "BarChart",
      "size": "md",
      "data": [
        {"name": "Page A", "uv": 4000, "pv": 2400, "amt": 2400},
        {"name": "Page B", "uv": 3000, "pv": 1398, "amt": 2210},
        {"name": "Page C", "uv": 2000, "pv": 9800, "amt": 2290},
        {"name": "Page D", "uv": 2780, "pv": 3908, "amt": 2000},
        {"name": "Page E", "uv": 1890, "pv": 4800, "amt": 2181},
        {"name": "Page F", "uv": 2390, "pv": 3800, "amt": 2500},
        {"name": "Page G", "uv": 3490, "pv": 4300, "amt": 2100}
      ],
      "xaxis": {
        "dataKey":"name"
      },
      "bars": [{
        "dataKey": "pv"
      }, {
        "dataKey": "uv"
      }]
    }]
  }
}

Available properties

Property Type Description Default
data object[] the data source for the bar chart -
bars object[] bars array, to see available properties refer to Recharts -
xaxis object to see available properties refer to Recharts -
yaxis object to see available properties refer to Recharts -
dataOptions.groupBy boolean if true, groups values by xaxis.dataKey false
dataOptions.hideZero boolean if true, hides bars whose value is equal to 0 false
showLabel boolean if true, display value on each bar false
legend boolean if true, display chart legend true
size string container width sm | md | lg | xl | 2xl | full lg

Pie Chart

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "PieChart",
      "size": "sm",
      "data": [
        {"id": "elixir", "label": "elixir", "value": 166},
        {"id": "stylus", "label": "stylus", "value": 71},
        {"id": "javascript", "label": "javascript", "value": 296},
        {"id": "haskell", "label": "haskell", "value": 305},
        {"id": "scala", "label": "scala", "value": 16}
      ]
    }]
  }
}

Available properties

Property Type Description Default
data object[] the data source for the pie chart -
legend boolean if true, display chart legend false
radialLabels boolean if true, enable radial labels false
size string container width sm | md | lg | xl | 2xl | full lg

Chart

A chart composed of line, area, and bar charts.

For the chart component, we are using an open-source composable charting library Recharts

Message output JSON example

{
  "output": {
    "hala": [{
      "type": "chart",
      "size": "md",
      "data": [
        {"name": "Page A", "uv": 4000, "pv": 2400, "amt": 2400},
        {"name": "Page B", "uv": 3000, "pv": 1398, "amt": 2210},
        {"name": "Page C", "uv": 2000, "pv": 9800, "amt": 2290},
        {"name": "Page D", "uv": 2780, "pv": 3908, "amt": 2000},
        {"name": "Page E", "uv": 1890, "pv": 4800, "amt": 2181},
        {"name": "Page F", "uv": 2390, "pv": 3800, "amt": 2500},
        {"name": "Page G", "uv": 3490, "pv": 4300, "amt": 2100}
      ],
      "xaxis": {
        "dataKey":"name"
      },
      "charts": [{
        "type": "bar",
        "dataKey": "pv"
      }, {
        "type": "line",
        "dataKey": "uv"
      }]
    }]
  }
}

Available properties

Property Type Description Default
data object[] the data source for the composed chart -
charts object[] an array of ChartType -
xaxis object to see available properties refer to Recharts -
yaxis object to see available properties refer to Recharts -
size string container width sm | md | lg | xl | 2xl | full lg

ChartType properties

Depending on the type property you can pass the rest properties from Area Chart, Bar Chart, Line Chart

Property Type Description Default
type string chart type, bar | line | area -

Support

Legal

Subscribe to our newsletter

The latest news, articles and resources, sent to your inbox weekly.

Linkedin Twitter

© 2021 HALA Digital OU. All rights reserved.