Settings

The Cognitive Flow settings are not related to a particular conversation but configure some general features of your bot.

The default settings for your bot 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 here.

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.

google-api-key

This is an API key from the Google Cloud Platform used to display location picker inside the webchat.

"settings": {
  ...
  "google-api-key": "AIzbSyCL9VQSuhcpxKETowyUXGNqGNw-i1yFp8A"
}

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"
    }
  }
}