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.


In addition to the webchat channel, other Azure Bot Framework channels can be enabled for your instance on request. Submit a request via customer support services from your management portal by navigating to Question menu > Support link.

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.

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 an action with this code:

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

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

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

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