Skip to main content
Skip table of contents

Chat Tab

Chat Settings (Autocorrect)

The autocorrect feature is available in all types of OCP miniApps® and allows you to specify a custom autocorrect model that will be used for correcting spelling mistakes in the chat.

To be able to use autocorrect in your web-chat, please contact our Support by any convenient means described in the Omilia Care (Support Center) section.

Rich Content

Below there are explanations about how to effectively utilize rich content (data models).

Rich content can be in the form of buttons, lists, selectable menus, calendars and other forms in the chat.

To select which type of rich content you want to create, click the +Add button and select the one you want from the list.

2025-03-07_09-59-02.png

You can add more than one data models to a miniApp, however maximum two data models can be added to each prompt.

Click the +Add link to rich content button to add rich content to any of the following actions:

  • Initial Prompt (Prompts, Conditional rephrase)

  • Reask Prompts

  • Manage Intents (Intent Disambiguations, Intent Confirmations)

  • Announcements Meta Data Model

The data model must be selected in the Prompts tab in order to be applicable.

Buttons Data Model

The buttons data model will create a button selection in the chat that will direct the caller to specific choices. These can be popular chat inquiries.

Chat with selection buttons

To add selection buttons to the chat, follow the steps:

1. Add the following details to a buttons data model:

  • Friendly name. This is how you can label your data model and later refer to it in any section that the +Add link to rich content button can be found (0 link is first, 1 link is second).

    You can add rich content to any of the following actions:

    • Welcome Prompts (Prompts, Conditional rephrase)

    • Reask Prompts

    • Manage Intents (Intent Disambiguations)

    • Announcements

  • Title. The text header that will be seen by the user on top of the button list. (Optional)

2. Add the following details to the selected button:

  • Label. The actual text that will show on the button.

  • Entities. NLU entities, which will help you specify metadata for each button and get a more precise result based on what the user selects. This can either be a selected intent from the list of intents available in the miniApp or a selected entity. Select any entities from the list and click the +Add entity button to add them.

    • For Intent select one from the list.

    • For Entities add a text value.

You can add as many buttons and data models as you want, but you may only use two data models for the same prompt.

Examples of additional buttons are shown below.

Meta Data Data Model

Metadata consists of custom key-value pairs that developers can configure to return to a specific dialog step. Although this content is not visible in the widget, the host website can retrieve it by implementing a callback JavaScript function within the widget's configuration.

The website developer can use these any way they see fit, for example, redirect, change DOM, and so on.

To add metadata from the chat, follow the steps:

  1. In the ChatRich Content tab click the +Add button on the data models line and select Meta Data.

  2. Add the following information in the new Data Model and save changes.

    • Friendly Name: This is how you can label your data model and later refer to it in any section where the +Add link to rich content button can be found.

    • Key: Set additional key values by clicking the + sign

    • Value: The value of the key. This value can be dynamic.

  3. Add the corresponding rich content to any of the actions that can receive rich content:

    • Welcome Prompts (Prompts, Conditional rephrase)

    • Reask Prompts

    • Manage Intents (Intent Disambiguations)

    • Announcements

Adding MetaData at any stage of the chat sends the configured data as an event in the website’s JavaScript. This data can be exploited in any way found useful.

For more information on how to use metadata on the client side read Chat widget integration guide.

List Data Model

The List data model allows creating a list of boxes that can contain pictures, information, and clickable links that can redirect to your site or any external URL.

2025-04-03_12-25-03.png

To add link data to a chat, follow the steps:

  1. Click the +Add button on the data models line and select List:

  2. Fill in the details of the data model. The Title and Subtitle will appear in the Chat in the corresponding box.

  3. Click the +Add button on the options line and fill in the details of that option. Every data model can have several options. An option can be a product or a product category you offer. For example, if the data model concerns bank loans the options could be the loan types.
    The info will be added to the corresponding box in the chat.

  4. Click the +Add button on the links line to add a URL link to the chat in the box of Option 1. The link will appear in the corresponding chat with the text in the Label field. You can add several links if required by repeating the process.

  5. Click the +Add Semantics button to add an entity from the list of entities or add a custom one. Fill in a semantic for that entity to complete this step.

  6. Repeat steps 3 to 5 to create another option for the data model.

JSON Data Model

For an even more customized result, there is the option to create a JSON Data Model for the chat widget.

2025-03-07_10-09-07.png

The JSON data model supports the following component types:

  • DATETIME - Can be used either as a date or a time picker.

  • BUTTONS - List of buttons.

  • FORM - Forms support INPUT and DROPDOWN components only.

    • INPUT - Text input, used inside forms only.

    • DROPDOWN - Used inside forms only.

DATETIME

DATETIME JSON Schema
JSON
{
  "type" : "object",
  "properties" : {
    "type": {
      "type": "string",
      "const": "DATETIME"
    "semantics_key" : {
      "type" : "string",
      "description" : "The semantics key for user input."
    },
    "free_text_enabled" : {
      "type" : "boolean",
      "default": true,
      "description" : "When set to true, the user can provide their input."
    },
    "with_calendar" : {
      "type" : "boolean",
      "default": false,
      "description" : "Indicates that item is a calendar. Can be `true` only if 'with_time' is `false'"
    },
    "with_time" : {
      "type" : "boolean",
      "default": false,
      "description" : "Indicates that item is a timepicker. Can be `true` only if 'with_calendar' is `false'"
    },
    "format" : {
      "type" : "string",
      "description" : "This will be used by the connector to construct the utterance that will show in the user's text bubble when a date is selected. If it is not set, the default will be set by the connector using FormatStyle.MEDIUM for date and FormatStyle.SHORT for time."
    },
    "submit_button_label" : {
      "type" : "string",
      "description" : "The label for confirmation button."
    },
    "validation" : {
      "type" : "object",
      "description" : "The rules for the user input",
      "properties" : {
        "available_dates" : {
          "type" : "array",
          "description" : "Dates that are allowed to be selected, in YYYY-MM-DD format",
          "items" : {
            "type" : "object",
            "properties" : {
              "start" : {
                "type" : "string",
                "format": "date",
                "description" : "The start date inclusive."
              },
              "end" : {
                "type" : "string",
                "format": "date",
                "description" : "The end date inclusive."
              }
            }
          }
        },
        "time_step" : {
          "type": "integer",
          "enum": [1, 5, 10, 15, 20, 30],
          "description": "Time step in minutes for the time picker."
        }
      }
    }
  },
  "required": ["type", "semantics_key"]
}

DATETIME can be used to select either a date or a time.

DATETIME cannot be placed inside a FORM.

Date Example

JSON
{
    "type": "DATETIME",
    "free_text_enabled": true, 
    "with_calendar": true,
    "format": "dd-MM-YYYY",     
    "submit_button_label": "Confirm",
    "semantics_key": "date", 
    "validation": {
        "available_dates": [
            {
                "start": "2025-02-20",
                "end": "2025-02-25"
            },
            {
                "start": "2025-03-01",
                "end": "2025-03-10"
            }
        ]
    }
}

Property Name

Type

Description

Type

string

Defines the type of the JSON Data Model.

semantics_key

string

 semantics key for user input

free_text_enabled

boolean

When set to true, the user can also use the free text input box to provide their input. Otherwise, they can provide their input only through the rich content component. Default is true

with_calendar

boolean

Indicates that item is a calendar. Can be true only if with_time is false

with_time

boolean

Indicates that item is a timepicker. Can be true only if with_calendar is false

format

string

This will be used by the connector to construct the utterance that will show in the user's text bubble when a date is selected. If it is not set, the default will be set by the connector using FormatStyle.MEDIUM for date and FormatStyle.SHORT for time

submit_button_label

string

The label for confirmation button

validation

object

The rules for the user input

available_dates

array

Dates that are allowed to be selected in YYYY-MM-DD format.

time_step

integer

Time step in minutes for the time picker. Allowed values are: 1, 5, 10, 15, 20, 30

Widget output example

Time Example

JSON
{
    "type": "DATETIME",
    "free_text_enabled": true,
    "with_time": true,
    "format": "mm:hh",     
    "submit_button_label": "Confirm",
    "semantics_key": "time", 
    "validation": {
        "time_step": 15
    }
}

Widget output example

BUTTONS

BUTTONS JSON Schema
JSON
{
  "type" : "object",
  "properties" : {
    "type": {
      "type": "string",
      "const": "BUTTONS"
    },
    "layout": {
      "description" : "Specifies how buttons should be arranged.",
      "enum" : ["HORIZONTAL", "VERTICAL"],
      "default" : "HORIZONTAL"
    },
    "label" : {
      "type" : "string",
      "description" : "The label to display for buttons."
    },
    "free_text_enabled" : {
      "type" : "boolean",
      "default": true,
      "description" : "When set to true, the user can provide their input."
    },
    "options" : {
      "type" : "array",
      "description" : "Options which will be represented as buttons.",
      "items" : {
        "type" : "object",
        "properties" : {
          "label" : {
            "type" : "string",
            "description" : "The label of the button."
          },
          "semantics" : {
            "type" : "object",
            "description" : "The data which will be returned to the connector when button is selected.",
            "additionalProperties" : {
              "type" : "string"
            }
          }
        },
        "required": ["label", "semantics"]
      }
    }
  },
  "required": ["type", "options"]
}

This will create a list of buttons arranged horizontally.

BUTTONS cannot be placed inside a FORM.

Example

JSON
{
    "type": "BUTTONS",
    "free_text_enabled": true,
    "label": "Sellect one of the options", 
    "options": [
        {
            "label": "Button 1",
            "semantics": {
                "key1": "value1",
                "key2": "value2"
            }
        },
        {
            "label": "Button 2",
            "semantics": {
                "key1": "value1",
                "key3": "value3"
            }
        },
        {
            "label": "Button 3",
            "semantics": {
                "key3": "value4"
            }
        }
    ]
}

Property Name

Type

Description

Type

string

Defines the type of the JSON Data Model.

layout

string

Specifies how buttons should be arranged. Allowed values are HORIZONTAL and VERTICAL. Default value is HORIZONTAL.

Label

string

The label to display for buttons

free_text_enabled

boolean

When set to true, the user can provide their input

options

array

Options which will be represented as buttons

label

string

The name of the button

semantics

string

Key value

Property free_text_enabled defines if the user is allowed to provide text response (if set to true) or forced to use the rich content for a response (if set to false). Default is true.

Widget output example

FORM

FORM JSON Schema
JSON
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "const": "FORM"
    },
    "fields": {
      "type": "array",
      "description": "Fields of the form.",
      "items": {
        "oneOf": [
          {
            "$ref": "#/definitions/DROPDOWN"
          },
          {
            "$ref": "#/definitions/INPUT"
          }
        ]
      }
    },
    "label": {
      "type": "string",
      "description": "The label to display for form."
    },
    "free_text_enabled": {
      "type": "boolean",
      "default": true,
      "description": "When set to true, the user can provide their input."
    },
    "submit_button_label": {
      "type": "string",
      "description": "The label for submit button."
    }
  },
  "required": ["type", "fields", "label"],
  "definitions": {
    "INPUT": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "INPUT"
        },
        "label": {
          "type": "string",
          "description": "The label to display for dropdown."
        },
        "semantics_key": {
          "type": "string",
          "description": "The semantics key for user input."
        },
        "value": {
          "type": "string",
          "description": "Prefilled value."
        },
        "placeholder": {
          "type": "string",
          "description": "Placeholder that will be displayed by web-chat widget for the input."
        },
        "error_message": {
          "type": "string",
          "description": "Message to display if the value does not comply with the validation rules."
        },
        "validation": {
          "type": "object",
          "description": "The validation rules the value should comply.",
          "properties": {
            "regex": {
              "type": "string",
              "description": "Regular expression that the input must match."
            },
            "min_length": {
              "type": "integer",
              "description": "Minimum length of the input."
            },
            "max_length": {
              "type": "integer",
              "description": "Maximum length of the input."
            }
          }
        },
        "required": {
          "type": "boolean",
          "description": "If set to true, widget won't allow to submit a form without it."
        }
      },
      "required": ["type", "semantics_key", "label"]
    },
    "DROPDOWN": {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "const": "DROPDOWN"
        },
        "label": {
          "type": "string",
          "description": "The label to display for dropdown."
        },
        "semantics_key": {
          "type": "string",
          "description": "The semantics key for user input."
        },
        "value": {
          "$ref": "#/definitions/DROPDOWN_OPTION"
        },
        "placeholder": {
          "type": "string",
          "description": "Placeholder that will be displayed by web-chat widget for the input."
        },
        "error_message": {
          "type": "string",
          "description": "Message to display if the value does not comply with the validation rules."
        },
        "autocomplete": {
          "type": "object",
          "properties": {
            "type": {
              "type": "string",
              "description": "Options extraction type",
              "enum": [
                "JMESPath"
              ]
            },
            "options_path": {
              "type": "string",
              "description": "Expression that specifies how options should be extracted from response of Autocomplete API"
            },
            "headers": {
              "type": "object",
              "description": "Headers which should be present in request to Autocomplete API",
              "additionalProperties": {
                "type": "string"
              }
            },
            "method": {
              "type": "string",
              "description": "HTTP method for request to Autocomplete API, default method is GET"
            },
            "url": {
              "type": "string",
              "description": "URL for the request"
            },
            "body": {
              "type": "string",
              "description": "Body of the request"
            },
            "search_term": {
              "type": "string",
              "description": "The name of placeholder for search term, the default is 'searchTerm'"
            }
          },
          "required": ["type", "url", "options_path"]
        },
        "options": {
          "type": "array",
          "description": "Options for the dropdown.",
          "items": {
            "$ref": "#/definitions/DROPDOWN_OPTION"
          }
        },
        "required": {
          "type": "boolean",
          "description": "If set to true, widget won't allow to submit a form without it."
        }
      },
      "required": ["type", "semantics_key", "label"]
    },
    "DROPDOWN_OPTION": {
      "type": "object",
      "description": "Prefilled value.",
      "properties": {
        "label": {
          "type": "string",
          "description": "The label of the option."
        },
        "value": {
          "type": "string",
          "description": "The value of the option."
        }
      },
      "required": ["value", "label"]
    }
  }
}

The rich content item that allows you to place inputs and dropdown list inside of it.

Currently, only INPUT and DROPDOWN fields are allowed.

Example

JSON
{
    "type": "FORM",
    "label": "Enter your data",
    "fields": [
        {
            "type": "INPUT",
            "label": "Full name",
            "semantics_key": "fullName"
        },
        {
            "type": "DROPDOWN",
            "label": "Preferred contact method",
            "semantics_key": "contactMethod",
            "options": [
                {
                    "label": "By phone",
                    "value": "phone"
                },
                {
                    "label": "By email",
                    "value": "email"
                }
            ]
        }
    ]
}

Property Name

Type

Description

type

string

Defines the type of the JSON Data Model.

label

string

The label to display as headline for the form

fields

array

Fields of the form. Can be either DROPDOWN or INPUT

free_text_enabled

boolean

When set to true, the user can provide their input

submit_button_label

string

The label for submit button

Widget output example

INPUT

Input is a type of form field which allows users to type their input.

Example

JSON
{
    "type": "INPUT",
    "label": "First name",
    "required": true,
    "value": "Name",
    "placeholder": "Type your name here",
    "error_message": "error",
    "semantics_key": "firstName",
    "validation": {
        "regex": "^[A-Za-z\s]+$",
        "min_length": 5,
        "max_length": 20
    }
}

Input specific Properties

Property Name

Type

Description

required

boolean

When property required is set to true, the widget won’t allow to submit a form without the field filled. Default is false.

value

string

Contains the pre-filed value for input

semantics_key

string

Used to specify under which semantics key the selected value will be extracted.

error_message

string

Contains a message that will be displayed if the input to the field doesn’t pass validation.

DROPDOWN

The dropdown component allows the user to type in order to filter the contents of the dropdown. This can be static or use autocomplete.

Example:

JSON
{
    "type": "DROPDOWN",
    "label": "Enter your data",
    "required": false,
    "value": { "label": "bbb", "value": "222" },
    "error_message": "error",
    "semantics_key": "lastName",
    "options": [
        { "label": "aaa", "value": "111" },
        { "label": "bbb", "value": "222" }
    ]
}

Dropdown specific Properties

Property Name

Type

Description

required

boolean

When property required is set to true, the widget won’t allow to submit a form without the field filled. Default is false.

value

array

Contains the pre-filed value for input

label

string

Label to be displayed by widget

value

string

Value to be extracted

semantics_key

string

Is used to specify under which semantics key the selected value will be extracted.

options

array

Each item there should have a label and a value. label will be displayed by widget, value will be passed on as output.

label

string

Label to be displayed by widget

value

string

Value to be extracted

Widget output example

Screenshot 2025-04-12 at 15.53.13.png
DROPDOWN with autocomplete

It has almost the same structure as dropdown with static options, the only difference is that instead of options  it has autocomplete configuration.

Example

JSON
{
    "type": "DROPDOWN",
    "label": "Address",
    "semantics_key": "addressId",
    "required": true,
    "placeholder": "Chose your address",
    "value": {
        "label": "Some address",
        "value": "ADRESS_ID"
    },
    "autocomplete": {
        "type": "JMESPath",
        "headers": {
            "Referer": "${ocpHost}"
        },
        "method": "GET",
        "url": "http://example.autocomplete.api/AddressComplete/SearchTerm=${userUtterance}",
        "options_path": "Items[].{value:Id, label:join('',[Text || '', Description || ''])}",
        "body": "The user typed: ${userUtterance}",
        "search_term": "userUtterance"
    }
}

Dropdown with autocomplete specific Properties

Property Name

Type

Description

required

boolean

When property required is set to true, the widget won’t allow to submit a form without the field filled. Default is false.

value

array

Contains the pre-filed value for input

label

string

Label to be displayed by widget

value

string

Value to be extracted

semantics_key

string

Is used to specify under which semantics key the selected value will be extracted.

autocomplete

array

Each item there should have a label and a value. label will be displayed by widget, value will be passed on as output.

type

string

The type of expression. Only JMESPath is supported

headers

string

The placeholder ${ocpHost} is supported in headers. It means that this value will be replaced by actual host of OCP (for example useast.dev.ocp.ai)

method

string

The API method

url

string

The URL path

options_path

string

Contains an expression for extraction of necessary information

Chat Widget

In the Chat Widget tab, you can configure how the chat window itself will look. Configure any of the following:

  • Title: The title of the chat

  • Color: The color of the font

  • Logo: The picture appearing on the top of the chat

  • Bubble: The picture appearing as a chat icon

  • Locale: The phoneme for the chat

With the configurations described in this article, the resulting widget will look as follows:

Embed Chat widget to a website

To embed the Chat widget to your website:

  1. Click the enable <<Locale>>  button.

2. Copy the Javascript code with the Copy button and paste it to your website’s HTML code. Otherwise copy only the API key from the JS code.

Test Webchat

Click the Try webchat! button to test the webchat.

Edit the Webchat Transfer module configuration

Click the edit button to open the Webchat configuration.

  1. Click the Transfer module toggle button to on to open the configuration options. The configuration options are different depending on the Type selection.

  2. Select the Transfer module Type (CFront, InContact, or Talkdesk)

    1. If InContact is selected the following options are available:

      • Poc: NICE point of contact, NICE queue ID.

      • Region: The region your application is based

      • Access key id: NICE access key ID

      • Access Key secret: NICE access secret key. This should be encrypted the same way the api_secret in the tenants table is encrypted.

      • Agent idle timeout: The maximum amount of time (in minutes) without receiving any new agent message. After that the conversation gets terminated. Zero value means no timeout.

      • No agent available message: Displayed to the user when we fail to start a transfer to NICE for any reason

      • Agent session timeout message: Displayed to the user when the agent has not responded after the set Agent idle timeout period has passed

      • User has left message: Displayed to the agent when the user has left the conversation

    2. If CFront option is selected the following options are available:

      2024-04-05_16-28-16.png
      • System id: CFront API key, it allows access to the CFront API

      • CFront service id: CFront queue id

      • Base url: CFront API URL

      • Generic error message: Message when an unexpected error has occurred

      • No agent available message: Displayed to the user when there is no available agent at that time

      • Agent session timeout message: Displayed to the user when the agent has not responded after a period has passed

      • User has left message: Displayed to the agent when the user has left the conversation

      • Agent has left message: Displayed to the user when the agent has left the conversation

      • Add Attachment: Required if the endpoint provided uses base 64 for authentication. The end-user can attach there the following information:

        • endpoint: The endpoint of the service

        • username: The username

        • password: the base 64 password

        • created by: This field is optional

          2024-07-26_13-26-16.png

    3. If Talkdesk option is selected the following options are available:

      • Account name: Talkdesk account name

      • Auth client id: Talskdesk authentication client ID

      • Region: Account and API region. Accepted values - EU, CA, US

      • Auth client secret: Talkdesk Authentication Client Secret. Encrypted with encryption key using AES256

      • Touchpoint id: Talkdesk touchpoint ID

For more information on how to embed a chat widget in your website read the Chat widget integration guide.

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.