Create a mental health screener with Azure Health Bot

Post image

In this article, you will learn how to author a custom scenario in Azure Health Bot. You will create a mental health bot that assess the severity of depression using the PHQ-9 questionnaire.

You will learn how to:

  • Author a simple custom scenario.
  • Create a RegEx language model.

To complete the exercise, you will need:

Create a custom scenario

  1. Sign in to Azure Health Bot management portal and in the Scenarios tab, select Create new scenario.

    How to create a new custom scenario
  2. In the New scenario window, enter the following information:

    • Name: Mental Health Bot
    • Description: A mental health bot that assess the severity of depression using the PHQ-9 questionnaire.
    • Scenario ID: phq9_scenario and click Create.
    New custom scenario details
  3. Once the scenario is created, you will be redirected to the Designer visual interface. You will build your scenario using the available conversational, flow control and advanced functionality elements in the top menu.

    Custom scenarios' building blocks in the Designer
  4. Select the Prompt control and drag it onto the canvas. Fill out the required properties:

    • Display text: Hello, welcome to the Patient Health Questionnaire. I am going to ask you a few questions. Your answers will help in understanding problems that you may have. Do you want to start the PHQ-9?
    • Variable name: start_phq9
    • Variable data type: choice
    • Choices Array: ['Yes', 'No']
    • Show Choices as: button
    Prompt control details
  5. Then, drag a Branch element onto the canvas and enter the following command: ${start_phq9}.entity == "Yes"

  6. Connect the output port of the Prompt control to the input port of the Branch element.

    Custom scenario pipeline in the Designer
  7. Drag a Statement block and enter Thanks. Goodbye! in the Display text field. Connect the left output node (No) of the Branch element to the input node of the Statement block.

  8. Add a Statement block and add this text in the Display text field: Over the last **2 weeks**, how often have you been bothered by any of the following problems?. Connect the right node (Yes) of the Branch element to the input node of the new Statement block.

    Custom scenario pipeline in the Designer
  9. Select the Action element and drag it to the canvas. Add the following script which creates an array of the 9 questions and the 4 possible answers and initializes the question index and score. We will then use the q_index variable to display each question of the questions array.

    ${questions} = [
        "Little interest or pleasure in doing things?",
        "Feeling down, depressed, or hopeless?",
        "Trouble falling or staying asleep, or sleeping too much?",
        "Feeling tired or having little energy?",
        "Poor appetite or overeating?",
        "Feeling bad about yourself - or that you are a failure or have let yourself or your family down?",
        "Trouble concentrating on things, such as reading the newspaper or watching television?",
        "Moving or speaking so slowly that other people could have noticed? Or the opposite - being so fidgety or restless that you have been moving around a lot more than usual?",
        "Thoughts that you would be better off dead, or of hurting yourself in some way?"
    ${answers} = [
        'Not at all',
        'Serveral days',
        'More than half the days',
        'Nearly every day'
    ${q_index} = 0;
    ${score} = 0;
  10. Connect the two new nodes.

  11. Then, add a Prompt element in your scenario. Use the following properties:

    • Display text: ${questions}[${q_index}]
    • Variable name: answer
    • Variable data type: choice
    • Choices array: ${answers}
    • Show Choices as: button Connect the output node of the Action element to the input node of the Prompt element.
    Custom scenario pipeline in the Designer
  12. Drag a second Action element onto the canvas and add the following code (which increases by 1 the question index and calculates the current score):

    ${score} += ${answer}.index;
  13. Use a Branch element to check whether we have reached the last question. Use the following command:

    ${q_index} == ${questions}.length
  14. Connect the elements as shown in the image. This way you will create a loop using the last 3 blocks.

    Custom scenario pipeline in the Designer
  15. Then, use an Action element to calculate the total score and the depression severity.

    var score = ${total_score};
    if (score <= 4) {
    } else if (score > 4 && score <= 9) {
      ${severity}="mild depression";
    } else if (score > 9 && score <= 14) {
      ${severity}="moderate depression";
    } else if (score > 14 && score <= 19) {
      ${severity}="moderately severe depression";
    } else {
      ${severity}="severe depression";
  16. Connect the right node (Yes) of the previous Branch element to the input node of the Action element.

    Custom scenario pipeline in the Designer
  17. Lastly, add a Statement element to display the result to the end-user. Use the following text: "Depression Severity: " + ${severity}

    Custom scenario pipeline in the Designer
  18. Click Save and use the Run button to test your scenario.

Language models

Let’s close the Designer and return to the health bot management portal. Click on the webchat icon and type begin phq9_scenario (where phq9_scenario is the ID of our new scenario) to trigger the mental health scenario.

Trigger the new scenario using the begin keyword

The next step is to create a language model which understands end user’s intention and triggers the relevant scenario. For example, you can use a language model to trigger the PHQ-9 scenario when a user types “I want to start the PHQ-9 questionnaire”.

There are different types of language models. In this article, I will show you how to create a simple RegEx language model to understand when a user is asking to start the PHQ-9 questionnaire.

Add a RegEx language model

Regular Expression (RegEx) models use a sequence of characters to specify a search pattern. For example, the RegEx pattern /phq-9/ would match the utterance “I want to start the phq-9 questionnaire”.

  1. In the management portal, navigate to Language > Models > New.

    Create a new language model
  2. In the New model window, fill out the following properties:

    • Name: PHQ-9 Questionnaire
    • Description: This model understands when a user is asking to start the phq-9 questionnaire.
    • Method: RegEx
    • Regular Expression: /phq-9|depressed/
    • Intent mapping: phq9-recognizer and select the phq9_scenario from the dropdown list.
    Details for new RegEx language model
  3. Open the webchat and type “I want to take the phq-9 questionnaire” to test the language model. This should trigger the phq9_scenario that we created.

    Test the language model in the webchat
  4. Type “I feel depressed”. This will trigger the triage and symptom checking scenario instead of the mental health scenario.

    Language models work in parallel. When an end user’s utterance is received, it is evaluated by all the language models. The language model with the highest confidence score wins and triggers the relevant scenario. Learn more about Language models in Azure Health Bot .

You can explore further Azure Health Bot’s language model by creating a LUIS model.


If you have finished exploring Azure Health Bot, you can delete your health bot instance and associated resources.

  1. In the Azure Portal , select Resource groups on the right menu and then select the resource group that you have created.
  2. Click Delete resource group.

You May Also Like