chatbot.yaml configuration file

chatbot.yaml is the main chatbot configuration file. It contains all configurable properties for the project, such as:

• The name of the main script file.
• Information on imported dependencies.
• NLU configuration.
• The list of included test files.

This article describes the properties which can be set in chatbot.yaml and their purpose.

Learn more about YAML syntax

Script entry point

entryPoint: main.sc

This property sets the script entry point – the file which is the first to load when the chatbot is deployed. The file must be located in the src folder and is conventionally named main.sc or entryPoint.sc.

When the script code consists of several files, all required files must be imported into the entry point itself or into files imported by the entry point. Use the require tag for importing files.

entryPoint is a required property.

Bot name

name: zb-cailapub

This property sets the bot name, by which it will be referenced in deploy logs and other system messages. If the property is missing, the internal project name will be used instead.

NLU settings

Bot engine

botEngine: v2

This property sets the chatbot engine version.

The second bot engine (v2) enables the CAILA service for implementing NLU (Natural Language Understanding). This is the recommended setting for all new projects.

If the property is missing or has a value other than v2, the legacy bot engine (v1) will be used instead. This engine allows only patterns for NLU.

Bot language

language: en

This property sets the language the bot will understand. The value should be a language ISO code.

When using the second bot engine, setting this property is required.

Classifier thresholds

sts:
  noMatchThreshold: 0.2
caila:
  noMatchThreshold: 0.2

The noMatchThreshold properties determine the classifier threshold values and should only be set when using the second bot engine. This is how they work:

1. The client sends a request to the bot.
2. The classifier determines the possible classes which the request can fall under and calculates a probability score for each one.
3. Classes having a probability score less than noMatchThreshold are discarded and ignored during subsequent request processing.

In other words, noMatchThreshold is the minimum required similarity of the request to one of the classes. The closer its value is to 1, the stricter are the matches that it requires.

An optimal value for this setting was empirically determined to be 0.2.

Thresholds set in the caila and sts sections apply to the CAILA NLU service and the deprecated example-based classifier respectively.

$context.nBest length

nlp:
  nbest: 3
  nbestPatterns: 1
  nbestIntents: 2
  nbestExamples: 3

Properties beginning with nlp.nbest determine the number of activation rules available from the script via the $context object.

• The nbest property sets the length of $context.nBest – an array of activation rules of all possible types (patterns, intents, and examples) triggered for the request. The default value is 1.
• nbestPatterns sets the length of $context.nBestPatterns – an array of activation rules only triggered by patterns. The array is unavailable if this property is omitted.

nbestIntents and nbestExamples work the same with respect to intents and examples.

Learn more about $context.nBest

Request processing limits

Request length limit

nlp:
  lengthLimit:
    enabled: true
    symbols: 100
    words: -1

nlp.lengthLimit sets a length limit on requests processed by the bot:

• enabled enables or disables the limit.
• symbols is the maximum number of characters contained in the request.
• words is the maximum number of words in the request. This limit is disabled if set to -1.

By default, the limit is enabled and set to 400 characters. The word limit is disabled.

If the request exceeds one of the limits, the lengthLimit event will be triggered.

Request processing timeout

nlp:
  timeLimit:
    enabled: true
    timeout: 500

nlp.timeLimit sets a limit on the time allotted for processing the request:

• enabled enables or disables the limit.
• timeout is the maximum time allowed for request processing, in milliseconds.

By default, the limit is enabled and set to 10000 (10 seconds).

If the request exceeds the limit, the timeLimit event will be triggered.

XML tests

tests:
  include:
    - "authorization.xml"
    - "integration-tests/*.xml"
  exclude:
    - "broken.xml"
  caseSensitive: false

You can use XML tests to verify the chatbot script by emulating client requests and asserting that bot responses behave as expected. The tests are executed automatically when the bot is deployed.

Even one failed test makes the whole deployment fail. New changes will not be made available in the channel on a failed deployment.

By default, all tests contained in the test folder are executed. You can override this behavior by setting the values for include and/or exclude in the tests section:

• include – only the tests from the files matching the patterns listed in this subsection will be executed.
• exclude – all the files matching the patterns listed in this subsection will be excluded from execution.

Apache Ant syntax is used for patterns.

The caseSensitive property determines whether patterns should be case-sensitive. It is true by default.

Dependencies

dependencies:
  - name: common
    type: git
    url: https://<repository>
    version: heads/master

The dependencies section contains a list of project dependencies.

Learn more about dependencies

Error messages

messages:
  onError:
    locales:
      en: Failed on request processing.
      ru: Что-то пошло не так.
    defaultMessage: Something went wrong.
    # defaultMessages:
    #   - Sorry, the bot just crashed.
    #   - An error occurred when processing your request.

The messages.onError allows setting the text of the message the chatbot will send if any errors occur in the script.

The locales subsection should contain messages localized based on user locale data. In this subsection, the keys are language ISO codes, and the values are the message texts themselves.

In the defaultMessage property, you can configure the text which will be sent by default if the necessary language or the locales section itself is missing. You can also set a list of such messages in defaultMessages, in which case a random error message will be chosen every time.

If the whole messages.onErrorsection is missing, the bot will not respond at all if an error occurs.

Use error handlers to set up a more flexible error processing behavior.

Injector

injector:
  catchAllLimit: 10
  api:
    protocol: https
    host: example.com
    port: 443

Use the injector section to set up the chatbot configuration. All properties will be accessible from the chatbot script via the $injector variable.

Learn more about $injector

Other settings

Request modification

nlp:
  modifyRequestInPreMatch: true

When enabled, the nlp.modifyRequestInPreMatch property allows modifying the request content in the preMatch handler, e.g. changing the request text.

Word tokenization in patterns

tokenizeWordsInPatterns: true

The tokenizeWordsInPatterns property enables word tokenization in patterns for languages without word separators.

This property is required for projects in Chinese so that patterns work correctly.

File import strategy

scenarioLoadStrategy: v2

The scenarioLoadStrategy property sets the strategy for loading files into the script consisting of multiple files. The property has two possible values: v1 (set by default) and v2. When using the v1 strategy, required files are loaded in the top-to-bottom order in the dependency tree, while v2 makes them load from bottom to top.

The following example illustrates the difference. The main.sc file imports r1.sc, r2.sc, and r3.scusing the require tag, and both r1.sc and r2.sc also have two imported files. When the script is deployed, the files will be loaded in the order illustrated in the image below.

Influence of context distance on intent score

nlp:
  considerContextDepthInStateSelectionV2: false

The nlp.considerContextDepthInStateSelectionV2 property determines whether the context distance to states triggered by the intent/intent! tag should be taken into account when calculating intent scores.

• true (default value) — context distance is used for calculating intent scores and selecting the target state.
• false — intent scores do not depend on context distance and are calculated the same way in all states.