There may be cases where your bot needs to perform certain actions based on conditional or branching logic. To execute this, you will use the IF instruction .

This instruction looks at a user query to determine that certain criteria are present in the submitted query. If the condition specified is true then your bot will start executing a nested series of steps. These steps live under a conditional branch where you will specify a series of instructions for the bot to run through. Steps within the conditional branch will be completed separately from any other instructions listed outside of the IF instruction.

If you want to have a more complex nesting of instructions, you can also add IF instructions within IF instructions for a goal.

Setting up an IF Instruction

There are two main steps you need to complete to set up an IF instruction type:

1. Specify the condition
2. Determine the instructions for the conditional branch

After you click +Add Instruction and select the IF action, you will see the option to add a condition instead of an instruction/instruction description. This tells your bot what it should be looking for to trigger the set of instructions within the conditional branch.

Within the conditional branch, you will make a new set of instructions that the bot needs to follow if that IF instruction is triggered. Setting up this branch follows the same conditions as setting up the instructions for a single goal.

Single IF Instruction Example

Below we will walk through the details of setting up a conditional IF instruction with the “get a demo” goal use case. We are going to build on the collect instruction example we outlined in the previous unit.

For a quick refresher - the goal is “get a demo” and the instructions are to collect the user’s email address if they enter phrases such as “I’d like a demo” or “I’d like to speak with a salesperson”. Then the bot can collect contact information for the user so a sales team can follow up with them.

However, you may want to get more specific with the information you are trying to collect. For example, in that collect instruction, we are asking the user for their email address and they can enter any email address - work or personal. If you want to be sure to collect their corporate email so you can identify the company they work for, then you can add a conditional follow-up step to help you collect this information.

You can do this in a variety of ways - you could add a conditional step to state that if they provide a personal email address, we’d like to then ask for their corporate email address. Or, you can add a step that if they provide a personal email address, you can ask them for the name of the company they work for. It all depends on what inputs you want the user to provide to the bot.

The instructions for a goal like that might look like this:

1. Ask the user for their email address. (Collect)
2. If it’s a personal email address (e.g., ends in “gmail.com”), also ask the user for the name of their company. (IF with Collect)
3. Reply to the user thanking them and letting them know we’ll be in touch shortly. (REPLY)

To set up the IF instruction, click Add Instruction and select an IF action. You will need to enter details of the condition in the text box. In this example the condition would be “If the user provides a personal email address (e.g., ends in “gmail.com”), also ask the user for the name of their company.” This would look something like this:

Once you add an IF instruction to your set of goal instructions, you will need to configure the conditional branch. To do this, click Add Instructions within the conditional branch. In your conditional branch, you will create a set of instructions with a collect instruction to gather the company name from the user.

Instructions within the conditional branch are only executed if the specified condition is met. So in this example, if a user provides a corporate email address in the first response, the conditional step will be skipped, and the bot will thank them for getting in touch.

Multiple IF Instructions Example

An example of using multiple IF instructions may be that you want to direct users to information about products and services when they ask about them. However, there may be a case where the information you want to show them lives within different data sources.

You could create a goal called “Answer Product and Services Questions”. For the instructions of this goal you could have two IF instructions each with their own instructions if the criteria is found to be true.

The first IF instruction (i.e.,criteria) would be that if a user wants to hear about services, the bot should:

1. Use the collect instruction to find out what services they are interested in.
2. Use the search instruction to utilize Yext Search to find services information within the Knowledge Graph.

The second IF instruction (i.e.,criteria) would be if users want to learn about products for sale, the bot should:

1. Use the collect instruction to find out about the products they are interested in.
2. Use the REST API instruction to get that information from an external data source.

Lastly, the bot should respond with the information found regardless of which criteria the user was looking for.

Nested IF Instructions Example

It’s also possible to have IF steps within other IF instructions, creating complex, doubly- or triply-nested instructions. This can be helpful if you are composing complex workflows for the bot that combine multiple different nested conditions.

To continue with the “get a demo” example from earlier, the chatbot will ask the user for their email. If it’s a personal email, the bot will ask for their company name. After getting the company name, the bot will then check if it’s a tech company. If it is, the bot will ask for the user’s role within the company. Lastly, the bot thanks the user and informs them that they’ll be in touch.

The instructions for a goal like that might look like this: 1. Ask the user for their email address. (Collect) 2. If it’s a personal email address (e.g. ends in “gmail.com”), also ask the user for the name of their company. (IF with Collect) * If the name looks like a tech company, ask for the user’s role within the company (Nested IF with Collect) 3. Reply to the user thanking them and letting them know we’ll be in touch shortly. (Reply)

Terminating Nested Steps

It’s important to understand when working with IF steps that a reply step always terminates the instructions, no matter where it’s encountered. This means that, once a bot has completed a series of nested steps, if it doesn’t encounter a reply step, it will move on to the next step outside of the if step.

JSON Configuration

Very often, you’ll need your bot to perform conditional or branching logic. This can be accomplished with an if step. In an if step, the model evaluates a user-defined condition and if the condition is true, it starts executing a nested series of steps. (This works exactly like the “if” statement in most programming languages, where the program starts executing a nested block of code.)

Here’s a very simple example in which the bot first collects a user’s email and then, if it looks like a personal email address, it will also ask the user what company they work for.

{
  "instructions": [
    {
      "collect": {
        "instruction": "Ask the user for their email address",
        "fields": [
          {
            "id": "email",
            "type": "EMAIL",
            "optional": false,
            "description": "The user's email address"
          }
        ]
      }
    },
    {
      "if": {
        "condition": "If the user's email address looks like a personal email address (e.g. gmail.com, yahoo.com, etc.)...",
        "steps": [
          {
            "type": "COLLECT",
            "description": "Ask the user for their company name.",
            "fields": {
              "company": {
                "type": "STRING",
                "description": "The user's company name",
                "required": true
              }
            }
          }
        ]
      }
    },
    {
      "reply": {
        "instruction": "Thank the user and tell them we'll be in touch.",
        "mode": "CONVERSATIONAL"
      }
    }
  ]
}

Nesting Steps

It’s also possible to have if steps within other if steps, created complex, doubly- or triply-nested instructions. This can be very helpful if you are composing very complex workflows for the bot that combine multiple different nested conditions.

In the example below, the chatbot will ask the user for their email. If it’s a personal email, the bot will ask for their company name. After getting the company name, the bot will then check if it’s a tech company. If it is, the bot will ask for the user’s role within the company. Lastly, the bot thanks the user and informs them that they’ll be in touch.

Terminating Nested Steps

Lastly, it’s important to understand when working with if steps that a reply step always terminates the instructions, no matter where it’s encountered. (This is a lot like a return keyword in programming - no matter where it’s encountered it stops executing the code and returns a value.)

This means that, once a bot has completed a series of nested steps, if it doesn’t encounter a reply step, it will move on to the next step outside of the if step. Let’s revisit this simple example:

{
  "instructions": [
    {
      "collect": {
        "instruction": "Ask the user for their email address",
        "fields": [
          {
            "id": "email",
            "type": "EMAIL",
            "required": true,
            "description": "The user's email address"
            }
        ]
      }
    },
    {
      "if": {
        "condition": "If the user's email address looks like a personal email address (e.g. gmail.com, yahoo.com, etc.)...",
        "steps": [
          {
            "type": "COLLECT",
            "description": "Ask the user for their company name.",
            "fields": {
              "company": {
                "type": "STRING",
                "description": "The user's company name",
                "required": true
              }
            }
          }
        ]
      }
    },
    {
      "reply": {
        "instruction": "Thank the user and tell them we'll be in touch.",
        "mode": "CONVERSATIONAL"
      }
    }
  ]
}

After the user finishes “Ask the user for their company name” step, the bot moves outside of the conditional step and onto the next step. In other words, it moves from step 2.1 to step 3.

After the user finishes the “Ask the user for their company name” step, the bot moves outside of the conditional step and onto the next step. In other words, it moves from step 2.1 to step 3.

Mutually Exclusive Conditions

This also means that you can create mutually exclusive conditional steps to ensure that the bot only goes down one potential path. You can do this by creating multiple successive if statements with mutually exclusive criteria and ensuring that they all contain a reply step.

Consider this example, in which the bot asks the user what type of insurance they’re looking for and performs different, mutually exclusive logic depending on the type.

{
  "goal": "Get a quote for insurance",
  "instructions": [
    {
      "collect": {
        "instruction": "Ask the user what type of insurance they're looking for",
        "fields": [
          {
            "id": "insuranceType",
            "type": "ENUM",
            "enumValues": [
              {
                "value": "Auto",
                "description": "Auto Insurance"
              },
              {
                "value": "Life",
                "description": "Life Insurance"
              },
              {
                "value": "Home",
                "description": "Home Insurance"
              }
            ],
            "required": true,
            "description": "The type of insurance the user is interested in"
          }
        ]
      }
    },
    {
      "if": {
        "condition": "If the user is looking for auto insurance...",
        "steps": [
          {
            // Steps for handling auto insurance
          },
          {
            "reply": {
              "instruction": "Thank you for your interest in our auto insurance. We'll be in touch soon.",
              "mode": "CONVERSATIONAL"
            }
          }
        ]
      }
    },
    {
      "if": {
        "condition": "If the user is looking for life insurance...",
        "steps": [
          {
            // Steps for handling life insurance
          },
          {
            "reply": {
              "instruction": "Thank you for your interest in our life insurance. We'll be in touch soon.",
              "mode": "CONVERSATIONAL"
            }
          }
        ]
      }
    },
    {
      "if": {
        "condition": "If the user is looking for home insurance...",
        "steps": [
          {
            // Steps for handling home insurance
          },
          {
            "reply": {
              "instruction": "Thank you for your interest in our home insurance. We'll be in touch soon.",
              "mode": "CONVERSATIONAL"
            }
          }
        ]
      }
    }
  ]
}

In this example, the bot first asks the user what type of insurance they’re looking for. Depending on the user’s response, the bot performs a specific set of actions for auto, life, or home insurance, and then concludes with a unique reply message for each type of insurance.

Each reply message serves as a termination point for that conditional branch, ensuring that only one set of steps is performed based on the user’s initial response.