Source: microsoft.com

The Microsoft Graph integration enables the Cognigy.AI virtual agent to log in a user to a specific Microsoft Azure Directory Tenant. With this login process in mind, the virtual agent is now able to use the Microsoft Graph API in order to execute multiple functions. In a chat conversation, the user now can be greeted with their real name, schedule new meetings in their calendar, send a message to a team's channel, and more. This tutorial will explain how to integrate an organization's Microsoft Active Directory to a Cognigy.AI virtual agent.

• Technical Documentation & Source Code

Table of Contents

1. Install the Microsoft Graph Extension
2. Login to Microsoft
3. Create a Microsoft Graph Connection
4. Retrieve Microsoft User information
5. Schedule a Meeting in Outlook Calendar
6. Exposed Flow Nodes

Install the Microsoft Graph Extension

The first step is to install the required integration. In this case, a so-called Extension is installed to Cognigy.AI. Thus, navigate to the Extensions Marketplace in the Virtual Agent and add the Microsoft Graph Extension by clicking on the Install button. Now follow this installation guide and upload the Extension to Cognigy, where it will be displayed as the following:

Congrats! The installation of the Extension is finished!

Login to Microsoft

Before Cognigy.AI can connect to Microsoft, a new App Registration needs to be created inside of the Microsoft Azure Portal. In order to do so, please contact an Azure Administrator in your organization and follow the steps of this tutorial. In the end, the whole authentication process looks like the following:

1. First, the Sign in With Microsoft button (see below) needs to be displayed in the webchat window.
   
   
   
   1. Important: One needs to download and install the Microsoft Auth Webchat Plugin in order to display the button! Please find the technical documentation here. How such a plugin can be installed, is explained here.
2. As soon as the user clicks on it, the webchat redirects the user to the Microsoft Login Page (https://login.microsoft.com) for OAuth2 authentication.
3. After providing their username and password, a so-called Microsoft Authentication Code (temporarily limited token) is sent to a specified redirect URI (/auth-callback.html).
4. Now, this redirect URI forwards the provided Authentication Code back to the webchat window so that it can be sent to Cognigy.AI.
   1. Important: The redirect URI and the webchat need to be in the same network so that they can reach each other.
   2. Note: The redirect URI sends an invisible message, including the Authentication Code, to Cognigy.AI. One can use the following Cognigy Script inside of an IF Node to check this incoming message: input.data.microsoftAuth.code:
      
5. Cognigy.AI uses this temporary Authentication Code in order to retrieve the final Access Token which is required for the Microsoft Graph API. Inside a Flow, the Get Access Token Node is used that send the Client ID, Client Secret, Scope, and Authentication Code to the final Microsoft Login service (https://login.microsoftonline.com).
   
   
   
6. Last but not least, the Access Token is sent back to Cognigy.AI and stored in the Context object. From now on, all Microsoft Graph Flow Nodes can be used.

Create a Microsoft Graph Connection

In this step, a so-called Connection will be created. This is required for using the authentication Flow Nodes, such as Get Access Token. If one, in Cognigy.AI, clicks on the previously uploaded Extension, the following details can be observed:

The red-marked part in the above figure shows, that there is a Connection required. Therefore, it needs to be created and filled with the Salesforce instance information. In order to do so, one initial Microsoft Graph Flow Node needs to be added to a Flow:

1. Create a new Flow in Cognigy.AI
2. Inside of the Flow Chart, click on + and navigate to the Microsoft Graph Extension:
   
   
   
   
3. For example, add the Display Sign In Button Flow Node by clicking on it:
   
   
   
   
4. In order to edit the Flow Node and create the Connection, please click on it. An Edit Node menu will be opened on the right side of the screen:
   
   
   
   
5. Right next to the Connection field (the first one at the top), one needs to click on the + button. The Connection menu will be opened at the center of the screen:
   
   

6. Both authentication nodes, Display Sign In Button and Get Access Token need to use the following Cognigy Connection in order to access the Microsoft Azure App Registration:

   • clientId
     • key: clientId
     • value: The Azure App Registrations client ID

   Login to portal.azure.com and create a new App registration. After this, you will see your client ID.

   • clientSecret
     • key: clientSecret
     • value: The Client Secret of your App registration

   One needs to click on Certificates & Secrets in the left side menu and create a new Client secret.

7. Click on the Create button

Retrieve Microsoft User information

After successful authentication, the virtual agent can confirm this by displaying the information of the current user. This can be done with the Get User Details Flow Node:

The result of this Node should be stored in the Context in order to make further use of it. For example, the virtual agent could display a single gallery item, containing the info:

Edit Menu:

Inside of the Chat:

Schedule a Meeting in Outlook Calendar

Next to this confirmation message from above, more functional features could be used as well -- such as scheduling a meeting with attendees inside of a virtual agent conversation. The Schedule Meeting Flow Node provides all necessary options for an upcoming calendar event:

The configuration shown above can be inserted automatically as well -- using Cognigy Script. Therefore, the virtual agent could ask multiple questions and then configure the event:

Exposed Flow Nodes

All in all, the following Flow Nodes can be used based on the Microsoft Graph Extension:

• Authentication:
  • Display Sign In Button
  • Get Access Token
  • Get User Details
• Outlook E-Mail:
  • Send Mail
• To Do:
  • Create To Do
  • Get To Do Lists
• Teams:
  • Send Channel Message
• Outlook Calendar:
  • Schedule Meeting
  • Get Events from Calendar