Steps Configuration

Learn what are the properties you can configure for each step of your bot’s conversations.

Types of Steps

One conversation can have multiple steps of different types.

The types are:

• question - allows you to extract a specific entity from a conversation and preserve it in the bot memory.
• message - simply send a message to the user
• command - commands are not messages visible by the user but tell the chatbot how to continue.
• webhook - retrieve or send REST API requests
• confirmation - prompt user for confirmation
• entities-confirmation - prompt user for confirmation of several entities
• conversation - executes the steps defined in a support conversation as part of the current conversation

Question Step

A question step allows you to extract a specific entity (think of it as an object) from a conversation and preserve it in the bot memory.

The variable name where the user response is stored is defined with the entity property, and the type of the extracted data is defined in entity-type.

In order for NativeChat to recognize an entity from a custom type, you should have previously trained your bot for this entity type in the Entities Training.

type

The type of the step - question. In this section, all of the examples are of type question.

entity

The name of the variable which will hold the extracted object from the conversation.

entity-type

The type of extracted data, it can be either built-in entity types like Text, Date, Time, Number, File, Location, Confirmation, or a custom entity type that is already defined in the Training definition.

capture-multiple-values (optional)

Setting capture-multiple-values to true will convert the entity variable into an array of items of type entity-type. In the example below, selectedDoctors will become an array that will hold values of the custom entity-type Doctor.

{
  "steps": [
        {
          "type": "question",
          "entity": "selectedDoctors",
          "entity-type": "Doctor",
          "capture-multiple-values": true,
          ...
        }
      ]
}

entity-display (optional)

A formatted value that will be stored as an entity display value in the short-term bot memory.

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "entity-display": "{{selectedDoctor.Title}} {{selectedDoctor.FirstName}} {{selectedDoctor.LastName}}",
      ...
    }
  ]
}

messages

A set of messages that will be sent to a user.

You can define multiple variants of your message to the user, and NativeChat will pick one randomly.

Single message

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "What is the name of the doctor?"
      ]
    }
  ]
}

Multi-line message

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        "In order to book a doctor, we have one more step left.",
        "What is the name of the doctor?"
      ]
    }
  ]
}

Multi-line messages send randomly

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        [
          "In order to book a doctor, we have one more step left.",
          "What is the name of the doctor?"
        ],
        [
          "We are almost ready! This is the final step.",
          "What is the name of the doctor?"
        ]
      ]
    }
  ]
}

Image messages

Image messages and combinations of text and messages are supported as well. Images could be added anywhere where a plain text messages are supported, using the following format:

...
"messages": [
  {
    "type": "image",
    "url": "https://picsum.photos//50",
    "alt": "Empty image with width of  px."
  }
]
...

where

Here is an example in which we display a CAPTCHA image and ask the user to provide the text displayed on it.

{
  "steps": [
    {
      "type": "question",
      "is-explicit": true,
      "entity": "verificationCode",
      "entity-type": "Text",
      "messages": [
        [
          "In order to verify that you are not a bot, please enter the text that you see in this picture **CAPTCHA (r)**",
          {
            "type": "image",
            "url": "https://www.researchgate.net/profile/George_Loukas2/publication/220459388/figure/fig1/AS:305672878084096@1449889501199/Example-of-a-graphical-CAPTCHA-a-Com-pletely-Automated-Public-Turing-Test-to-Tell.png",
            "alt": "This text will be used fo accessibility by for example screen readers and by search engines"
          }
        ]
      ]
    }
  ]
}

ssml-messages (optional)

Like messages but marked up with SSML (Speech Synthesis Markup Language). The SSML markup is used when the message is pronounced thought the Amazon Alexa device. Check the Amazon SSML documentation for supported features.

Example:

{
  "steps": [
    {
      "type": "question",
      "entity": "selectedDoctor",
      "entity-type": "Doctor",
      "messages": [
        [
          "We are almost ready! This is the final step.",
          "What is the name of your doctor?"
        ]
      ],
      "ssml-messages": [
        [
          "<prosody rate='fast'>We are almost ready!</prosody> This is the final step.",
          "What is the name of your doctor?"
        ]
      ]
    }
  ]
}

display (optional)

Ability to provide quick replies or options from a static or dynamic list of values. The user can click on the provided responses or input free text.

Quick Replies

Read more about configuring how to display predefined replies.

reactions (optional)

Reactions define how NativeChat will react to a number of specified cases emerging from the value of the step’s entity. All reactions are processed before any step is executed.

Configuring Reactions

acknowledgments (optional)

Inform the user that the bot has understood a specific value. It will be used only when the bot identifies the entity without explicitly asking for it.

Here is an example of how the bot reacts when with the first message the user provides values for a few entities:

Configuring an acknowledgment

ambiguities (optional)

There are cases where a bot can identify multiple values for a given entity, and it will use the message to ask the user which one is correct.

An example how the bot reacts when with the first message the user asks about two doctors when in the cognitive flow we’ve defined only one slot for an entity of type doctor:

Configuring ambiguity handling

validations (optional)

A set of validation rules executed before the entity is persisted in the bot memory.

You can use the following validation types:

• phone
• email
• regex
• length
• range
• match
• image
• custom

Configuring Validations.

suggestions (optional)

It is used to suggest to the user some values for the entity, based on previous conversations. The suggestions reaction is only supported for steps that have no display at all or have quick-reply type of display.

Configure Suggestions.

is-explicit (optional)

NativeChat normally extracts the entities from the conversation with the user using Natural Language Processing (NLP). Alternatively, NativeChat can extract an entity only when it has explicitly asked the user for it. For example, if we are using a simple question to get a Yes/No response from the user, it’s a good idea to use the is-explicit property, so that the bot doesn’t fill it in from an unrelated utterance by mistake. Also, when a question for an is-explicit step has been asked, no other entities will be filled-in by the user’s response.

For entities of type Text, there are two explicit modes that can be specified — soft and hard and there’s only a slight difference in how they handle the user’s response to the question:

• Hard mode entirely skips the NLP. This means that if the user replies with a different question or a trigger phrase of another conversation, it won’t be understood by the bot. The text from the response will be taken verbatim, checked against the configured validations (if any) and will be assigned to the configured entity. To use this mode set the is-explicit property to one of true or "hard".
• Soft mode, on the other hand, calls the NLP and if the result matches a question from some Question answering category or a Conversation trigger, acts upon it instead of assigning the value to the entity. This mode can be set using the value "soft".

Setting the property to false or "" is equivalent to omitting it altogether and means that the entity could be set implicitly and the question might not be asked if the user happens to fill it in with a previous utterance. Also, note that Text entities are never filled-in implicitly, is-explicit can be used when you want to prevent filling-in other entities or to disable NLP when the question is asked.

{
  "type": "question",
  "entity": "confirmation",
  "entity-type": "Text",
  "is-explicit": "soft",
  "messages": [
    "Do you confirm your booking with {{selectedDoctor}}?"
  ],
  "display": {
    "type": "quick-reply",
    "data": [
      "Yes",
      "No"
    ]
  },
  "reactions": {
    "validations": [
      {
        "type": "match",
        "parameters": {
          "values": [
            "Yes",
            "yes"
          ]
        },
        "error-message": [
          "Please, enter the change that you would like to make to your appointment."
        ]
      }
    ]
  }
}

protected (optional)

You can set a step as protected, which will require the user to authenticate with his business account. More info

conditions (optional)

You can add a list of conditions to any step. The step will not be executed unless all of its conditions are evaluated as true. You can define conditions by using condition rules and checking the state of the Bot Memory.

"steps": [
  {
    "conditions": [
      "{{$has grade}}",
      "{{$lt grade 3}}"
    ],
    "type": "question",
    "entity": "knowledge",
    "entity-type": "Text",
    "messages": [
      "You need to say something smart in order to pass"
    ]
  },
  {
    "conditions": [
      "{{$has grade}}",
      "{{$gte grade 3}}"
    ],
    "type": "message",
    "messages": [
      "Congrats on passing the course!"
    ]
  }
]

is-private (optional)

If a step is marked as private, it’s entity value, debug and display data will not be persisted in the bot history. Be careful not to display the private entity in another step. If you need to do so, you have to mark the other step as private as well, so that the data is kept in transit only and no information is recorded on NativeChat’s servers.

"steps": [
  {
    "is-private": true,
    "type": "question",
    "entity": "name",
    "entity-type": "Text",
    "messages": [
      "What is your name?"
    ]
  },
  {
    "is-private": true,
    "type": "message",
    "messages": [
      "Hi {{name}}!"
    ]
  }
]

The bot responses from a private step, e.g. messages, acknowledgements, validation errors, etc., will be masked with ‘***’ and no debug logs will be attached to the message. If the bot understands a private entity from a user message, the message and the entities understanding will also be displayed as ‘***’.

In the conversation history the entity value will be displayed, like:

"Entities": {
  "name": {
    "displayValue": "***",
    "value": "***",
    "type": "Text",
    "isPrivate": true
  },
  ...
}

While debugging, you will see all the data in the debug console, but in the messages history the sensitive data will be removed.

Confirmation Step

A confirmation step allows you to confirm a specific action from the user. It’s very similar to the question step, and all properties that are valid for a question step definition are also valid for a confirmation step. The only difference is that the Cognitive Flow will append automatically quick replies for Yes/No. When the user selects a reply, this will set the step entity to true if the user confirms and false if the user rejects the confirmation.

{
  "steps": [
    {
      "type": "confirmation",
      "entity": "redirect",
      "messages": [
        "Do you want to continue the conversation with an operator?"
      ]
    }
  ]
}

is-private (optional)

Same as question step.

Entities Confirmation Step

Entities confirmation step allows you to confirm a list of entities. The bot will display quick replies with a confirmation button and a list of entity values that can be changed.

If the user selects a value, the bot will remove it from the bot memory and will ask again for it. If the user confirms, the step entity will be set to true.

type

The type of the step - entities-confirmation.

entity

The name of the variable which will hold the confirmation value.

entities

List of the entities that will be confirmed.

{
  "type": "entities-confirmation",
  "entity": "confirmAppointment",
  "entities": [
    "doctor",
    "date",
    "time"
    ],
  ...
}

messages

The same as in question step. The text should explain what will be confirmed and how the user can make a change.

{
  ...
  "messages": [
    [
      "I am booking you an appointment with {{doctor}} on {{date}} at {{time}}?",
      "Please, confirm or select the value that you want to change."
    ]
  ]
  ...
}

ssml-messages (optional)

Same as in question step.

display (optional)

You can change the text of the Confirm button with the button-text setting.

{
  ...
  "display": {
    "button-text": "Yes"
  }
}

conditions (optional)

Same as question step.

 "steps": [
   ...
   {
    "type": "entities-confirmation",
    "entity": "confirmBookDoctor",
    "entities": [
      "doctor",
      "date",
      "time"
    ],
    "messages": [
      [
        "I am booking you an appointment for {{doctor}} on {{date}} at {{time}}.",
        "Please, confirm or select the value that you want to change."
      ]
    ]
  },
  {
    "type": "webhook",
    "conditions": [
      "{{$eq confirmBookDoctor true}}"
    ],
    ...
  }
]

is-private (optional)

Same as question step.

Message Step

A message step is used to send a message to the user where you don’t expect any response. For example, the end of your process might be to provide a phone number to the user, so that he can contact your operator. You can use as parameters in your message every entity that exists in the bot memory by using the {{EntityName.EntityProperty}} syntax. More details on the formatting syntax can be found here.

type

The type of the step - question, confirmation, message or webhook. In this section, all of the examples are of type message.

messages

A set of messages that will be sent to a user. You can define multiple messages and they will be sent to the user randomly similar to the messages in a question step.

{
  "type": "message",
  "messages": [
    "You are making a good progress for booking an appointment with {{selectedDoctor}}. There are only a few minutes left before we are ready."
  ]
}

ssml-messages (optional)

Same as question step.

is-private (optional)

Same as question step.

Webhook Step

A webhook step is used to make a web service call. You can use it as a final step of your conversation to persist the gathered information in an external system, or simply notify an external system for an event. You can also store the result of a webhook as an entity in the bot memory.

type

The type of the step - question, confirmation, message or webhook. In this section, all of the examples are of type webhook.

data-source

Ability to call a web service with parameters from the short-term bot memory.

Read the external data-source article for full information.

{
  "type": "webhook",
  "data-source": {
    "endpoint": "https://mycustomwebsite.com/Appointments",
    "method": "POST",
    "headers": {
      "Authorization": "Bearer EuebDyjsd23PS20zY51ULlJSecFUenAkWN"
    },
    "payload": {
      "CabinetID": "1",
      "DoctorID": "{{selectedDoctor.DoctorID}}",
      "PatientIdentNumber": "{{contactNumber}}",
      "PatientMobile": "{{contactPhone}}",
      "PatientName": "{{contactName}}",
      "User": "{{user.Id}}"
    },
    "selector": "$.Result[:]"
  }
}

messages

A set of messages that will be sent to a user after the webhook is executed. You can define multiple messages and they will be sent to the user randomly similar to the messages in a question step.

ssml-messages (optional)

Same as question step.

entity (optional)

A name of the entity that will hold the result of the web service call in the short-term bot memory.

Let’s imagine that once a user makes an appointment with a doctor, the service returns a unique registration code that the user needs to present to the front-desk before his appointment. You can use two steps, one will be a webhook step to persist the appointment and the second will be a message step to display the registration code to the user.

{
  "steps": [
    {
      "type": "webhook",
      "entity": "responseAppointments",
      "data-source": {
        "endpoint": "https://mycustomwebsite.com/Appointments",
        "method": "POST",
        "headers": {
          "Authorization": "Bearer EuebDyjsd23PS20zY51ULlJSecFUenAkWN"
        },
        "payload": {
          "CabinetID": "1",
          "DoctorID": "{{selectedDoctor.DoctorID}}",
          "PatientIdentNumber": "{{contactNumber}}",
          "PatientMobile": "{{contactPhone}}",
          "PatientName": "{{contactName}}",
          "User": "{{user.Id}}"
        }
      }
    },
    {
      "type": "message",
      "messages": [
        "Thank you for making an appointment with us. Your personal registration code is {{responseAppointments.appointmentCode}} "
      ]
    }
  ]
}

is-private (optional)

Same as question step.

Conversation Step

Often different conversations have some similar steps and this leads to duplications. To avoid duplication, you can extract these steps in a separate conversation and reuse it in any other conversation.

To completely switch to another conversation, you can use a command step with go-to command.

{
  "conversations": {
    "getUserInfo": {
      "type": "support",
      "display-name": "get user info",
      "steps": [
        {
          "type": "question",
          "entity": "userName",
          "entityType": "Text",
          "messages": [
            "What's your name?"
          ]
        },
        {
          "type": "question",
          "entity": "userPersonalNumber",
          "entityType": "Number",
          "messages": [
            "What's your personal number?"
          ]
        }
      ]
    },
    "bookDoctor": {
      "type": "goal",
      "display-name": "book a doctor",
      "steps": [
        ...
        {
          "type": "conversation",
          "conversation": "getUserInfo"
        }
        ...
        {
          "type": "message",
          "messages": ["You have successfully booked a doctor."]
        }
      ]
    },
    "checkAppointments": {
      "type": "goal",
      "display-name": "check appointments",
      "steps": [
        ...
        {
          "type": "conversation",
          "conversation": "getUserInfo"
        }
        ...
      ]
    }
  }
}

type

The type of the step - conversation.

conversation

The name of the shared conversation to use.

conditions (optional)

You can add a list of conditions to any step. The step will not be executed unless all of its conditions are evaluated as true.

You can define conditions by using condition rules to check the state of the Bot Memory.

{
  "steps": [
    ...
    {
      "type": "conversation",
      "conversation": "getUserInfo",
      "conditions": [
        "{{shouldAskForUserInfo}}"
      ]
    }
    ...
  ]
}

Command Step

A command step allows you to execute specific commands. The commands have the following format:

[command-name] [command-parameter]

where [command-parameter] could be optional/unsupported depending on the command type.

type

The type of the step - command.

command

The type of the command to be executed. The following commands are supported:

• go-to
• invalidate-entity
• set-entity
• stay-silent

go-to

go-to [conversation name]

Use the go-to command to switch to another conversation. For example, after completing a conversation to ask for feedback. Or switch to another conversation based on some conditions.

{
  "conversations": {
    "bookDoctor": {
      "type": "goal",
      "display-name": "book a doctor",
      "steps": [
        ...
        {
          "type": "message",
          "messages": ["You have successfully booked a doctor."]
        }
        {
          "type": "command",
          "command": "go-to collectFeedback"
        }
      ]
    },
    "checkAppointments": {
      "type": "goal",
      "display-name": "check appointment",
      "steps": [
        ...
        {
          "type": "confirmation",
          "entity": "continueBooking",
          "messages": [
            "Do you want to book a doctor?"
          ]
        },
        {
          "type": "command",
          "command": "go-to bookDoctor",
          "conditions": [
            "{{$eq continueBooking true}}"
          ]
        },
        {
          "type": "message",
          "messages": [
            "OK, bye then."
          ]
        }
      ]
    },
    "collectFeedback": {
      "type": "goal",
      "display-name": "collect feedback",
      "steps": [
        ...
      ]
    }
  }
}

invalidate-entity

invalidate-entity [entity name]

Removes an existing entity from the Short-term Bot Memory.

{
  "type": "command",
  "command": "invalidate-entity doctor"
}

Instead of passing entity name as a command parameter following the command name, you could also set step’s entities property with a list of entities to be invalidated:

{
  "type": "command",
  "command": "invalidate-entity",
  "entities": [
    "doctor",
    "patient"
  ]
}

set-entity

Sets value to an entity in the Short-term Bot Memory. You could configure the command using the following step properties:

• entity is the name of the entity to be set. It could be a new one, or an entity which already exists in the short-term bot memory.
• entity-display is how the entity will be visualized.

To set the value of the entity, you could use any of the following properties:

• data is the static data that should be set to the entity. Could be primitive type (e.g. number, boolean), string, array, or object.

  {
    "type": "command",
    "command": "set-entity",
    "entity": "doctors",
    "data": [
      {
        "LastName": "Cannon",
        "FirstName": "Mary"
      },
      {
        "LastName": "Burke",
        "FirstName": "John"
      }
    ]
  }
  

• data-source specifies an entity from which data/value should be copied, with the following child properties:

  • entity is the name of the source entity, from which to extract data/value.

  • selector is a JSONPath expression to extract the result you need from the source entity. If selector is not specified, the value of the source entity is copied.

    For example, if we use the doctors entity from the previous example, we can select only doctors’ last names in a new entity using the following command:

  {
    "type": "command",
    "command": "set-entity",
    "entity": "doctorsLastNames",
    "data-source": {
      "entity": "doctors",
      "selector": "$[:].LastName"
    }
  }
  

stay-silent

stay-silent [(optional) minutes]

Once the user reaches this step, the bot will stay silent for the specified amount of time. This property is 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.

You can skip the command parameter and the silence-timeout setting will be used. If no timeout is defined, the command will be executed with 0.

• live-agent specifies the live agent to which the bot will transfer the user session, with the following properties:
  • transfer automatically transfer the session if true.
  • config-name is the name of a live agent configuration from the list with configurations in Live agent hand-off in bot settings.

{
  "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",
      "live-agent": {
        "transfer": true,
        "config-name": "my-live-agent-configuration"
      }
    }
  ]
}

Next steps

Working with bot memory - storing, retrieving and formatting data from bot memory during a conversation.