Settings

Learn about the Cognitive Flow settings that configure some general features of your bot.

The settings in the Cognitive Flow are not related to a specific conversation but define the general behavior of your bot.

The default settings are:

{
  "commands": {
    "NEXT-PAGE": [
      "Next 5"
    ]
  },
  "settings": {
    "invalid-replies": [
      "I am not sure I understood what you said."
    ],
    "general-failure": [
      "We are experiencing technical difficulties at this moment."
    ],
    "previous-conversation-messages": [
      "I am going back to {{ conversationDisplayName }} now."
    ],
    "silence-timeout": 60,
    "persist-entities": [],
    "timezone": "Universal"
  },
  "conversations": {}
}

general-failure

Default message that will be sent to the user in case your bot experiences technical difficulties.

invalid-replies

One or more messages that will be randomly sent to the user in case the bot cannot recognize the conversation or step that needs to be executed based on your defined training.

silence-timeout

The silence timeout setting in minutes will be used if no parameter is provided to the stay-silent command. The silence-timeout and stay-silent command are used to transfer the conversation to an operator, and mute the bot until the operator resolves the issue. The bot will reply to user message either when the timeout expires or if the user inputs the restart keyword.

timezone

If your chatbot is working with time you should specify a timezone from this list. It will enable the chatbot to understand correctly messages like "Now" or "after two hours". By default, it is set to Universal.

"settings": {
  "invalid-replies": [
    "I am not sure I understood what you said."
  ],
  "general-failure": [
    "We are experiencing technical difficulties at this moment."
  ],
  "previous-conversation-messages": [
      "I am going back to {{ conversationDisplayName }} now."
  ],
  "silence-timeout": 60,
  "timezone": "Europe/Sofia"
}

use-user-timezone

When working with dates and times you can personalize the experience by working in the user’s timezone instead in a single predefined one. This is useful for cases like scheduling an online meeting.

"settings": {
  "timezone": "Europe/Sofia",
  "use-user-timezone": true
}

If the user’s timezone is available, then the understanding and date formatting will use this timezone. However, if it’s not, then the bot’s timezone is used. Not all channels support this feature, so be sure to check channels feature comparison chart.

persist-entities

Persist entities setting provides an option to persist any entity in conversation. For example, if you have setup authentication for your bot and you want to persist authentication token after the conversation is completed you can use persist-entities.

"settings": {
  ...
  "authentication": {
    "entity": "yourBusinessAuth",
    "messages": [
      "You will need to login to your account before you can proceed."
    ],
    "acknowledgements": [
      "You are now logged in YourBusiness."
    ],
    "display": {
      "type": "login",
      "template": {
        "title": "YourBusiness SignIn",
        "url": "https://your.business.com/login",
        "image": "https://your.business.com/logo.png"
      }
    }
  },
  "persist-entities": [
    "yourBusinessAuth"
  ]
}

You can persist more than one entity from a conversation. For example contactEmail and contactPhone with following settings:

{
    ...
  "settings": {
    ...
    "persist-entities": [
      "contactEmail",
      "contactPhone"
    ]
  },
  "conversations": {
    "bookDoctor": {
      "type": "goal",
      "display-name": "book a doctor",
      "steps": [
        {
          "type": "question",
          "entity": "contactEmail",
          "entity-type": "Text",
          "messages": [
            "What is your Email?"
          ]
        },
        {
          "type": "question",
          "entity": "contactPhone",
          "entity-type": "Text",
          "messages": [
            "What is your Phone?"
          ]
        }
      ]
    }
  }
}

built-in-confirmations

Built-in confirmations provides the ability to display Yes/No quick replies in a confirmation step. NativeChat contains default configuration as listed below that you can customize if you want to:

"settings": {
  ...
  "built-in-confirmations": {
    "display-data": [
      "Yes",
      "No"
    ],
    "yes-values": [
      "Yes",
      "yes"
    ]
  }
}

Your confirmation step will automatically show the options defined in the display-data in the built-in confirmations. When the user selects or types something, we will match his response with the yes-values and if a match is found, the confirmation step entity will be set to true, false otherwise. For example, look at the following conversation definition that uses the confirmation step entity value to decide whether to redirect the user to operator or show help message.

"conversations": {
  ...
  "contactOperator": {
      "type": "goal",
      "display-name": "contact an operator",
      "steps": [
        {
          "type": "confirmation",
          "entity": "redirect",
          "messages": [
            "Do you want to continue the conversation with an operator?"
          ]
        },
        {
          "conditions": [
            "{{$eq redirect false}}"
          ],
          "type": "message",
          "messages": [
            "OK, I won't contact an operator yet. Let me know what you want to do next."
          ],
          "display": {
            "type": "quick-reply",
            "data": [
              "book a doctor",
              "book NST"
            ]
          }
        },
        {
          "conditions": [
            "{{$eq redirect true}}"
          ],
          "type": "message",
          "messages": [
            "I am transferring you to an operator, and I will stay silent for the next 60 minutes. If you want to get back to me, please type 'restart'."
          ]
        },
        {
          "conditions": [
            "{{$eq redirect true}}"
          ],
          "type": "command",
          "command": "stay-silent 60"
        }
      ]
    }
}

previous-conversation-messages

Previous conversation messages setting is used to inform the user that conversation is changed back to the previous unfinished goal conversation so the user can continue with it. The conversationDisplayName parameter is replaced with the unfinished conversation’s display-name property:

"settings": {
  ...
  "previous-conversation-messages": [
      "I am going back to {{ conversationDisplayName }} now."
    ]
}

authentication

Configures third-party authentication for the chatbot. See details here: Third-party authentication.

trusted-domains

An array of allowed origins for events coming from the webchat. Useful in Third-party authentication scenarios when the page sending the token to the webchat is not the same as the login form. The login form origin is allowed by default.

"settings": {
  ...
  "trusted-domains": [
    "https://your.business.com"
  ]
}

files

The files uploaded through the webchat / mobile channels are stored in Google Cloud Storage where a short-lived URL is generated to access the file. After the file expires, the file URL will no longer be active and the actual file will be deleted. You can use your own storage instead by providing a custom upload URL where the file data will be posted.

expiration-time

Sets the expiration time of the files uploaded by the user in seconds. The default expiration time for all files is 1 hour. The maximum expiration time is 1 day. Note that this setting is not relevant when upload URL is set.

{
  "settings": {
    ...
    "files": {
      "expiration-time": 300
    }
  }
}

upload-url

URL where the file data will be sent as form data. The expected response is:

{
  "FileName": "file name",
  "MimeType": "file mime type" ,
  "DownloadUrl": "url to the file"
}

The DownloadUrl property will be used in the file entity value.

Example:

{
  "settings": {
    ...
    "files": {
      "upload-url": "https://your.storage.url"
    }
  }
}

confidence-threshold

Confidence is the degree of certainty with which NativeChat identifies the entity, the conversation or the question in a user expression. Confidence is a percentage from 1 to 100. The confidence threshold is the number above which the bot will accept the user’s input. If the user expression does not contain any recognized entity or conversation trigger or question the bot will display the invalid-replies message. The default is 0.65 (or 65% confidence).

{
  "settings": {
    ...
    "confidence-threshold": 0.75
  }
}

service-limit-reached

When during a conversation with a user the bot reaches any of the limits such as number of concurrent users or conversations quota defined in the subscription plan the bot will display a message to the user. The default message is This service is not available right now. Please try again later. and can be customized with the service-limit-reached setting.

{
  "settings": {
    ...
    "service-limit-reached": [
      "This service is currently not available. Please try again later."
    ]
  }
}