IF (Conditional) Instruction Type | Yext Hitchhikers Platform

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.