Integrating The Health Bot

  • Article

Embed a health bot instance in your application

The Microsoft Health Bot Service provides health-related information to the end users. The partner's health bot instance may be implemented as a web chat element in the partner's web application. The health bot instance embedding should be done in a secured manner to avoid others impersonating a partner or a partner's users.

As part of the health bot instance embedding, the host application will typically want to use additional information sources to better personalize the scenarios---for example, provide ad-hoc user location, or access information systems to retrieve electronic medical records or health care providers' information.

Integration use-cases

  • Embedding the health bot instance in the host application.

    For example, implement the health bot instance as an iFrame or div element in the hosting web page.

  • Securing communications between the health bot instance and the host application.

    The secured integration is aimed to avoid application/user spoofing and eavesdropping.

  • Exchange of ad-hoc information between the host application and the health bot instance.

    For example, the application wants to pass user location information to the health bot instance.

Code samples

The integration scenarios are demonstrated with sample code in this GitHub repository.

Embedding of the health bot instance in the host application

The embedding of the Health Bot in the partner web/mobile application can be done as an iFrame or as a web page element (div embedding) as demonstrated in the GitHub repository.

Securing communications between the health bot instance and the host application

To secure the communications with the health bot instance, the host application should retrieve in advance two secrets, the app_secret and the webchat_secret. Secrets can be found in the keys tab of the tenant admin portal, as seen in the screenshot below:

Steps to securing communications

  1. Before the chat with the bot begins, the partner's service should create a security JWT token. This is typically triggered by a client-side chat request.

  2. The partner's service should acquire connectorToken---a token used to connect with the Microsoft Bot Framework Connector (aka Bot Connector). This token is provisioned as described in the Microsoft article Bot Framework Authentication. The webchat secret is required.

  3. The application service should prepare a security JWT token that will be returned as a response to the chat request. The JWT security token will be signed with the app_secret, and will contain the following elements:

    • user ID: A unique, consistent and unidentifiable user identifier that will help the health bot instance retrieve data about this user for better personalization. The tenant is expected to obfuscate the user ID in a way that only the tenant will be able to restore.

      Note: the tenant should make sure to generate a different user ID for different users, rather than use the same user ID for all the users.

    • connectorToken: as described above.

    • optionalAttributes: This is a JSON structure that describes optional application attributes that may be used in the Health Bot Service scenarios---for example, user location.

      An example of how to create the JWT token is provided in this Health Bot Container Sample GitHub repository.

  4. The application client side should start a web chat against the Bot Connector. This request should include the previously acquired connectorToken.

  5. Right after the chat connection is initiated the application client side should post an "InitAuthenticatedConversation" event that contains the previously acquired jwtToken.

    An example of the client-side code is provided in this Health Bot Container Sample GitHub repository.

Note: The secrets should be stored in a secure way on the partner application side and not exposed to the client side.

Require end user authentication via the JWT token The JWT token is not a strict requirement to communicate with the bot unless you enforce it in the Health Bot configuration. Navigate to Configuration >> Compliance >> Security >> End user authentication and enable the setting.

This will force the bot expect a JWT token and the conversation will not start unless the JWT token is received as part of every message sent from the webchat client.

Exchange of ad-hoc information between the host application and the health bot instance

The partner application service can send optional attributes while in chat session or as part of service side response. (See step 3 in the diagram above.)

Sending ad-hoc information in chat initiation

This GitHub code sample provides an example of how to pass ad hoc location information about the user.

The following is an example of the extraction code in the Health Bot Service Scenario Editor action element:

${lat} = @{initConversationEvent}.location.lat

Sending ad-hoc information while in chat

For example, to send user location while in chat, in the Scenario Editor you will have to write and action with this code:

var msg = new builder.Message(session);
msg.data.type = "event";
msg.data.name = "shareLocation";
msg.data.value = <your value object>;
session.send(msg);

On the client side, you will have to write this code:

botConnection.activity$.filter(
    activity => activity.type === "event" && activity.name === "shareLocation"
).subscribe(activity => getUserLocation(activity.value));

The getUserLocation method can be implemented based on browser supported capabilities.

Integrating your health bot instance with your data sources and APIs

Connecting to Data Providers APIs

There are multiple ways to connect the Health Bot Service with your data sources and APIs:

  • Non-user associated; for example, the API is used to get general information about a healthcare provider.

  • User associated:

    • In-chat explicit consent. For example, the API is used to retrieve the user's age, gender, and workout info from a social network. This requires the user's authentication and consent.

    • Single Sign On (SSO) mode. For example, the user is already signed in to the partner web application. The health bot instance can use the API to retrieve user's medical record from the partner system, without asking the user to sign in again.

Non-user-associated API

In this scenario, the access to the backend API is generic and not done on behalf of a user, therefore no user authentication or consent is required. For example, this type of access can be used to fetch information from a doctor's repository. Typically, the access to this API will be done with an API key that will be used in the Authorization header, another header, or as a URL parameter.

To implement this scenario, a new data provider with the appropriate type of API_KEY should be created.

When adding a new data provider in the Scenario Editor, the header or URL authorization parameter should be defined based on the API key variable.

The URL, method, and headers should also be configured.

User associated API

In this scenario, the health bot instance can connect in ad hoc mode to a REST API on behalf of the user. Typically, the resources provided by this API belong to the user, and the user should provide consent to access them.

The following is an example of accessing a social network to retrieve fitness information:

The steps to implement this scenario are:

  1. Create a new data provider of type OAuth.

  2. In the Scenario Editor, add a new data provider, linked to the provider created in step one.

The data provider should be configured with the URL, method, and other optional configurations.

SSO mode

In this scenario, the health bot instance can access backend API that belongs to the partner application. If the user is already signed in to the partner application, there is no need to ask them to sign in again to access the API. For example, this type of data can be used to fetch user profile information from the partner's system.

Step 8 in the following diagram illustrates how to use optional attributes to access the partner application API in SSO mode.

To implement this scenario, a new data provider of the type "Custom" should be added in the Scenario Editor.

In the data provider, the Headers:(object) field should be edited to generate the Authorization header. In the case of OAuth access key, the value in the Authorization header is based on the optional Attributes. See the example below:

Microsoft Health Bot Service management API

The Microsoft Health Bot Service provides API to enable programmatic management actions; for example, programmatic import and export of scenarios from the Scenario Editor.

How to use the API

Code samples

The provided code samples demonstrate how to use the API.

API structure

The API is implemented with REST architecture, enabling performance of CRUD operations on resources that are represented as URLs.

API security

The API is protected with standard JWT tokens. The JWT tokens contain two claims:

  • tenantName, taken from the management portal in the keys tab

  • iat, timestamp as an UNIX epoch value

The JWT token is signed with an API secret, called API_JWT_secret. The secret is taken from the management portal, as shown in the following screenshot:

An example of a JWT token payload before encoding is shown here:

{
    "tenantName": "myTenant",
    "iat":"1507056900"
}

The JWT token is placed in the authorization header, according to the following example:

  Authorization:_Bearer_eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0ZW5hbnROYW1lIjoibXlUZW5hbnQiLCJpYXQiOiIxNTA3MDU2OTAwIn0.MN4DcxO2mLsltEYNpXbC6T6Bjxj3-rxIAObngZIw4-U

It is recommended that the author implement the JWT tokens with standard libraries -- for example, Node.js jsonwebtoken library.