Teams Chatbot Flow

We will now use a Webhook Flow to develop a simple Teams Chatbot that will respond with inventory information when the bot is @mentioned. We will then use the message to extract inventory information from the database created in the Save To Database flow.

For this tutorial we will first build the Webhook Flow and then test it. Finally we will integrate it as the URL endpoint for a Teams Outbound Webhook. When a message such as @botname cpu" is received we will use the message contents (assumed to be the equipment id or name) to retrieve the inventory count for this equipment and post it back as a message to Teams.

Getting intermediate results

Whenever you need to get intermediate results from the integration or other steps added, connect the last node to Success and Run the Flow. You can now copy the results for further steps. You can also Save the Run if you want to permanently save the flow results.

Lets say for e.g you need to extract results from an HTTP call. Add the HTTP node and configure it. Connect the HTTP node to Success and Run the flow. The results are now displayed and you can copy the results of the HTTP call. Now add the JSON Parser node and use the copied results as an example input to extract data from.

Prerequisite - MS Teams

You will need access to an MS Teams and PowerApps environment. If your company is not using Teams, you can still sign up for a free account if you want to test this flow. Alternatively you can use a similar process (if the system supports it) to post a message to Turbo Apps from Slack or any other messaging tool as they all mostly follow the same process.

Webhook

You will need the webhook URL for the flow before configuring in Teams. Please complete Step 1 below to copy the URL.

1. Head over to Power Automate
2. On the left side-bar choose Create and search for webhook.
3. From the list of entries shown, select Post to a channel when a webhook request is received. and click Continue.
4. Now select the Team and the Channel you want to send the message to.
5. Complete the setup and close the pop-up window.
6. We now need to get the webhook URL. For that click on the Edit button.
7. From the list of nodes displayed select the first node ie. “When a Teams webhook is received”.
8. A properties window is displayed and you need to Copy the generated HTTP URL.

Thats it, we are now ready to build the flow.

Webhook Payload Format

To build the bot flow later, you will require the JSON payload format which is documented here: https://learn.microsoft.com/en-us/azure/bot-service/rest-api/bot-framework-rest-connector-api-reference?view=azure-bot-service-4.0

You can also configure the Outgoing webhook temporarily to point to a Request Bin or equivalent service that can save the post data for you to process. If you want to use Turbo Apps to determine that you can simply add an Email node to your flow and send a mail to yourself with the Email message set to flowinput so that the entire JSON is emailed to you.

Flow Development

1. In the Forms list, click on the Flows icon on the Computer Inspection row
2. A list of Flows will be displayed. Now click on the Create button and choose the Webhook Flow option
   • Title - Enter Teams Chatbot Webhook
   • Description - Enter description as Flow to query and post inventory to Teams on an @mention or similar
   • Expiry Date - Enter the date until when the webhook should be valid
   • Click on Save to create the flow
3. You will now be navigated to the Flow Builder

Understanding the steps

Before we develop the flow, let us draw a flow chart of the different steps we need to perform to return the inventory:

flowchart TD
    A([Start]) -->|Webhook Flow Trigger| B[Extract Equipment]
    B --> C{Error}
    C --> |No| D[Query Master Data for Equipment Inventory]
    C --> |Yes| E([ReturnError])
    D --> F{Error}
    F --> |No| G(Prepare MS Teams text message with count)
    F --> |Yes| E
    G --> H([Return Success])

Note

1. When a call is received, extract the equipment from Flow Input
2. Query the inventory master data for that equipment and return the count as a Teams text message
3. Return success or error

Developing the Flow

1. Remember for webhook flow there is no strict data format imposed. Data can be posted as post parameters or in the post body. Turbo Apps Flows will receive the input via the special FlowInput parameter in separate attributes as below. The body is saved as postbody and all other post parameters using the parameter name.

   {
       flowinput : {
           "postparam_1":"some value",
           "postparam_2":"some value",
           "postbody": {
               "bodyparam_1":"some other value",
               "bodyparam_2": {
                   "key","value"
               }
           }
       }
   }

   For the chatbot we are interested in the message posted in the body and hence we will be using the flowinput -> postbody for extraction.
2. In the Flow Builder, the Add Node dialog should already be open. If not, click on the Webhook Flow start node and then click on the :fontawesome-solid-circle-plus: icon that is displayed below the node
3. Search for the JSON Parser node by typing in json and clicking on it
4. The JSON Parser node is now opened and you can configure it.
   1. Change the title to Extract Equipment and remember to connect the Webhook Flow start node Success connector to this node (else the expression builder will not display all the possible fields and nodes)
   2. Since we want to work with the Flow Input, click on the Others section
   3. For Map Field Name select Flow Input
   4. We need the post message format which is documented here. We are primarily interested in the text attribute. The format is documented in the Azure Bot SDK documentation

      {
          "flowinput": {
              "postbody": {
                  "type": "message",
                  "serviceUrl": "https://smba.trafficmanager.net/amer/",
                  "channelId": "msteams",
                  "from": {
                  },
                  "conversation": {
                  },
                  "recipient": null,
                  "textFormat": "plain",
                  "locale": "en-US",
                  "text": "<p><at>TurboApps</at>&nbsp;computer</p>",
                  "attachments": [
                  {
                  }
                  ],
                  "entities": [
                  {
                  }
                  ],
                  "channelData": {
                  },
                  "callerId": "urn:botframework:azure"
              }
          }
      }

   5. Under Expression click on the :fontawesome-solid-wrench: icon to open the Expression Builder
   6. Copy and paste the Flow Input JSON above into the JSON window on the left
   7. The expression builder we use for JSON parsing is a tool called Jsonata
   8. We need to extract the name of the equipment from the text field. Additionally spaces are converted to the html   when pasted. Use the following expression to extract:

      $trim($replace($substringBefore($substringAfter($.postbody.text, "</at>"), "</p>"), "&nbsp;", " "))

   9. Paste the expression from the step above into the Mapping Expression window on the right. The extracted equipment computer is now displayed at the bottom. Confirm that what is displayed is correct.
   10. Now Click on Save and close the builder,
   11. Now Click on the :fontawesome-solid-floppy-disk: icon and save the node
5. Add a Master Data Read node by typing in read row and add the Read Rows node.
6. The Read Rows node is now opened and you can configure it.
   1. Change the title to Read Inventory and remember to connect the Extract Equipment node Success connector to this node (else the expression builder will not display all the possible fields and nodes)
   2. In the Master Data Entity dropdown, select Equipment Inventory
   3. Now for Master Data Filter, we are going to use the Query Builder to build a condition to filter the inventory master data on equipmentId equal to the extracted equipment
   4. From the dropdown select EquipmentId and the condition as Equals. Choose the Custom toggle and then click on the :fontawesome-solid-wrench: icon again to open the Expression Builder
   5. From the Previous option choose *Extract Equipment and then Result
   6. Click on save to close the query builder.
   7. Now click on the :fontawesome-solid-floppy-disk: icon and save the node
7. We now need to prepare the Teams message response. Click on the Read Inventory node and click on the :fontawesome-solid-circle-plus: icon that is displayed below the node
8. Search for the JSON Parser node by typing in json and clicking on it
9. The JSON Parser node is now opened and you can configure it.
   1. Change the title to Prepare Teams Message and remember to connect the Read Rows node Success connector above to this node (else the expression builder will not display all the possible fields and nodes)
   2. Since we want to work with the retrieved inventory, click on the Previous Steps section
   3. For Map Field Name select Read Inventory and then Result
   4. We need the message format returned by the Read Rows master data method. To get this intermediate result you can just type $. for the expression, connect the node and Run Flow. This will display the result format in the Trace window which you can copy and open this configuration again. The data will be similar to:

      {
      "data": [
          {
          "equipmentId": "computer",
          "submit": true,
          "inventory": 10
          }
      ]
      }

   5. Under Expression click on the :fontawesome-solid-wrench: icon to open the Expression Builder
   6. Copy and paste the Flow Input JSON above into the JSON window on the left
   7. The expression builder we use for JSON parsing is a tool called Jsonata
   8. We need to extract the inventory now. However remember that if the equipment was not found an empty array will be returned. So we use the $exists*() function to make sure that the attribute exists. Also we will be using data[0] as we want the first returned row.

      $.{"text" : $exists(data[0].inventory) ? "Inventory count is: " & $string(data[0].inventory) : "Equipment inventory not found for: " & "{'${'}extractequipment_result}"}

   9. Paste the expression from the step above into the Mapping Expression window on the right. The extracted equipment computer is now displayed at the bottom. Confirm that what is displayed is correct.
   10. Now Click on Save and close the builder,
   11. Now Click on the :fontawesome-solid-floppy-disk: icon and save the node
10. Last step, we need to return data exactly how the Teams bot framework expects. For this click on the Prepare Teams Message and click on the :fontawesome-solid-circle-plus: icon that is displayed below the node
11. Search for the Response node by typing in response and clicking on it
12. The Response node is now opened and you can configure it.
    1. Change the title to Send To Teams and remember to connect the Prepare Teams Message node Success connector above to this node (else the expression builder will not display all the possible fields and nodes)
    2. Select the Success option
    3. Set the HTTP Code to 200 to signify HTTP Success
    4. For Body click on the :fontawesome-solid-wrench: icon to open the Expression Builder
    5. Select Result below the Prepare Teams Message entry
    6. Now Click on the :fontawesome-solid-floppy-disk: icon and save the node
13. Connect the Send To Teams node to Success
14. Now click on Publish button to save and compile the Sub flow. If the compilation is successful it will also be published and we can run it to test.

Testing the Flow

1. Now that we have published the flow we are ready to test it. The Flow Builder has an integrated Run and Debug tool to help us troubleshoot the flow in case of errors.
2. Now click on the Run Flow button. The Run dialog is now displayed. Since this is the first time we are running the flow we need to enter Form (test) data now by clicking on the Form Data button and saving it.
3. Still in the Run Flow screen, copy the Teams Message JSON from above and paste it into the Flow Input field. The Flow Input now has the message that we want to process as though we received it from the bot.
4. Run the flow by clicking on the Run button. The flow should run successfully.
5. If there are errors it could be due to some mistakes while configuring the system or copy/pasting the expression or similar. Check each step carefully with the documentation above.
6. However we cannot check if Teams received your response yet. This is because we simulated the webhook call using Run Flow. We actually didn’t receive a call from MS Teams.

Testing with MS Teams

1. Login to the Teams App
2. Navigate to the Team to which you added the Outbound Webhook in the prerequisite step. Choose any channel under that team and click on New Post
3. In the new post type in @turboapps (or select it from the list that pops up) and then type in computer. What we are now going to do is to send a message to the Turbo Apps via the configured outbound webhook by clicking on Send
4. Wait a few seconds and you should see a message Inventory count is: 10*
5. Now send another message by typing in @turboapps watercooler
6. You should now get the response Equipment inventory not found for: watercooler. If you recall we didn’t add it to the inventory to simulate an error which we have now done!

Caveat: More steps needed for Production

THis tutorial was only meant as a means to help you learn how to build a chatbot. We have made some simplistic assumptions on the chat message content containing only the equipment ID. Additionally when the Outbound Webhook is created a HMAC key is displayed. It is recommended to follow the process recommended by Microsoft to compute the hash and compare it to the received hash for each message to ensure that you are receiving the message from the originally configured source. You can use a Javascript node in Turbo Apps flow builder to perform the computation or call an API to compute the same

Follow Along Video

Watch Video (opens new window)

Assignment

The flow above uses a Json Parser step to extract the message from the Flow Input field and process the input. We have made a very simple assumption that the user will @mention and then type in the equipment id. In reality the user is most likely to type in **Hey @turboapps can you check the computer inventory” or something similar. This process can be made better by using an LLM.

This is your assignment:

1. Copy the Teams Chatbot Webook flow to Teams Chatbot Webhook v2 using the Copy Flow option
2. Use OpenAI or any other LLM to process the input text message and extract the equipment id we need to fetch the inventory for.
3. Add a HTTP node and configure it to make a call to the LLM. Follow the OpenAI or the other LLM API docs to do this.
4. Use the returned entity to search in the Read Rows step. If the data from the LLM is returned in the form of a JSON, use a JSON Parser node to extract it and process.
5. You can also improve the process by searching for the inventory master data using Equipment Name or Equipment Id by adding an OR condition in the condition node.
6. After building it remember to change the outbound webhook URL in Teams and then test it

Check the solution for this assignment: Assignment Solution

Topics Covered

Note

The following concepts have been covered:

1. Configuring a webhook that can be involed from Teams to build a chatbot
2. Adding HTTP Server and the other parameters to POST a REST message call to MS Teams
3. Some more advanced JSONata expressions for no code JSON parsing
4. Working with Flow Input
5. Reading master data and filtering using conditions
6. Running the flow and testing it
7. Using JSON parser to prepare JSON output text message for Teams