Proactive Messaging in Microsoft Teams from Healthcare Bot service

This article is contributed. See the original author and article here.

 

There are many use cases in which organizations send push notifications to nudge their users to take an assessment or reply to a questionnaire. The Proactive Scenario API in Healthcare Bot service allows to initiate a scenario proactively. This documentation explains how to proactively invoke a scenario using Twilio SMS channel. Using the same principles, we will walkthrough the different steps to configure proactive messaging in Teams.

 

The configuration is done in 2 steps – 

Step 1: Register User ID and Teams Address

Step 2: Invoke scenario programmatically for all registered users

Below is a visual of the two necessary steps: 

 

 

Pre-requisites:

• Azure subscription, you will need to create additional Azure services to complete the configuration, ensure to have necessary access rights in your subscription. Login to https://portal.azure.com
• Microsoft Healthcare Bot service – Create a healthcare bot 
• A good understanding of creating Azure Functions and binding with data platforms such as Azure Table storage

 

Step 1: Register User ID and Teams Address

 

1. Login to Azure portal. Create a table to store – 

• User ID = Azure AD Object ID in case of Teams
• Address = Teams Address unique to each user

To save these 2 key-value pairs, there are many options available in Azure data platform including Table in Azure Data Lake storage Gen2, Cosmos DB Table API, Azure Cache for Redis and Azure SQL Database. We’ll create a Table in ADLS Gen2 with

1. Partition key = Azure AD Object ID,
2. Row key = <any random string> (teamsAddress as seen in screenshot below) Note: Address could not be stored in Row key because of limitation of 255 byte size 
3. Address = unique Teams Address
4. Timestamp

This is a screenshot of a table in ADLS Gen2 viewed in Azure Storage Explorer.

 

2. In Healthcare Bot service, enable Teams as UI channel using this link and test the bot in Teams.

 

3. In Healthcare bot, create a scenario with write function to the table created in step 1 above. A sample scenario can be found at this GitHub link. Basically you need two scenario elements in the scenario as shown below:

 

Scenario element 1: Init Action to extract Teams Address, Azure AD Object ID and generate a Timestamp

 

Scenario element 2: Ingest to table storage using table’s endpoint in the form – 

 

4. Manually invoke by writing ‘begin registeruser’ in Teams channel or you call healthcare bot from another bot in Teams. 

 

 

Step 2: Invoke scenario programmatically for all registered users

 

Once you have all of the user IDs and Teams addresses, an organization’s administrator can create an Azure function for Step 2 to set up a POST call trigger to send daily/regular notifications to registered users in Teams. You will need the POST call, the authorization token, and the body of the post call – all of which have to be created in an Azure function.

 

Note: A sample code is available in this GitHub link – this file is part of COVID-19 Back to Work solution and writes required User ID and Teams Addresses to Azure SQL database. We are using this repository for reference of Azure function. Use the code with caution and customize it to the Azure storage platform you chose in above step.

 

1. In this step, gather all information required for the POST request API call – 

1. Healthbot Trigger Call – choose based on your closest region

• US tenants – https://bot-us.healthbot.microsoft.com/api/tenants/<tenantName>/beginScenario
• EU tenants – https://bot-eu.healthbot.microsoft.com/api/tenants/<tenantName>/beginScenario

ii. Healthbot Tenant Name – Healthcare bot admin portal > Integration > Secrets > tenant name

iii. Healthbot API_JWT_SECRET_KEY – Integration > Secrets > API_JWT_Secret Key

iv. Healthbot ScenarioId – Scenarios > Manage page. Find the relevant scenario and copy its Scenario ID

 

Once you have these values handy, save them in Azure Function App’s Application Settings. 

 

2. JWT token for authentication in POST request header (GitHub – function GetJwtToken)

 

3. Read Teams Address of each recipient required in POST request body from Table storage. Create a binding between Azure function and Table storage using this link

 

4. Execute the Http or Timer Trigger POST call in Function App (GitHub – TriggerTeamsNotification.cs)

 

Additional Resources

• For using Azure Functions full codebase related to proactive messaging and using Azure SQL database as data source – COVID-19 Back-to-Work solution
• For getting started on Healthcare Bot and COVID-19 templates – Quick Start

 

Thanks for reading and let us know how else we can help!

Nikita Pitliya, Microsoft Senior Solutions Architect

 

Brought to you by Dr. Ware, Microsoft Office 365 Silver Partner, Charleston SC.