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

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.

A question step with predefined quick replies.

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 Kinvey Chat 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 Text, Date, Time, Number, File, Location and Confirmation or a custom entity-type that is already defined in the Training definition.

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 Kinvey Chat 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?"
        ]
      ]
    }
  ]
}

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

A question step with predefined quick replies.

Read more about configuring how to display predefined replies.

reactions (optional)

Reactions define how Kinvey Chat 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:

Acknowledgement reaction example.

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:

Ambiguity reaction example.

Configuring ambiguity handling

validations (optional)

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

Validation reaction example.

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)

Kinvey Chat will extract the entities from the conversation with the user using Natural Language Processing (NLP). Alternatively, Kinvey Chat can extract an entity only when it explicitly asks 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 parse it from a separate conversation without explicitly asking the user for it.

{
  "entity": "confirmation",
  "entity-type": "Text",
  "is-explicit": true,
  "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 Kinvey Chat’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.

Ambiguity reaction example.

{
  "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."
    ]
  ]
  ...
}

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

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. You can set endpoint, method, headers, payload and selector as options to the data-source property. The selector is an optional JSONPath expression to extract data from the HTTP response.

{
  "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.

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]

type

The type of the step - command.

command

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.

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

invalidate-entity

invalidate-entity [entity name]

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

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

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": [
        ...
      ]
    }
  }
}

Next steps

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