Content Comparison

This document provides examples showing how to integrate Personal Assistant chatbots Agent Chatbots into third-party web applications.

Prerequisites

• An instance of Personal Assistant Agent deployed

• A server with the third-party web application deployed

• Knowledge of web development

• Understanding of the PKCE authorization flow (applies only to internal chatbotsChatbots)

Obtaining the JavaScript Code Snippet

To integrate chatbotsChatbots, one first need to obtain the code snippet that facilitates communication with the Personal AssistantAgent. Follow these steps:

1. Navigate to the Personal Assistant Agent web page.

2. Go to the Chatbots page.

3. Click the three-dot menu on the right side of the chatbot Chatbot one wishes to integrate.

4. Select Code Snippet.

5. Save the code snippet in a JavaScript file (.js) on the web server where ones web application is deployed. The file name is not important, but for the purpose of this guide, we will assume it is named chatbot_client.js. Note that when

Overview of Code Snippets

The code snippet is available in two versions: one for public chatbots Chatbots and another for internal chatbotsChatbots.

Public Chatbot

The code snippet includes a single class, ChatbotClient, used to communicate with a chatbotChatbot. It defines three methods:

• connect(): Establishes a connection with the chatbotChatbot.

• sendMessage(message): Sends a message to the chatbotChatbot. It accepts the following parameter:

  • message: The message to be sent to the chatbotChatbot.

• close(): Closes the connection with the chatbotChatbot.

It also exposes three event listeners:

• onMessage: Triggered when a new message from the chatbot Chatbot arrives. It accepts a function with a message object as a parameter. The message object contains two string fields:

  • state: Indicates the current state of the message, which can have two values:

    • processing: The message is still being processed (more batches will arrive).

    • done: The entire message has been sent (no more batches will arrive).

  • message: The content of the message.

• onClose: Triggered when the connection to the chatbot Chatbot is closed. It accepts a function without any parameters.

• onError: Triggered when an error occurs during communication. It accepts a function with an Error object parameter.

Internal Chatbot

The code snippet includes two classes: ChatbotClient and AuthorizationService.

ChatbotClient is similar to the one for public chatbotsChatbots, with the only difference being the connect(token) function, which accepts a bearer access token as a parameter for user authentication.

...

• init(redirectUri): Initializes the authorization service. It accepts the following parameter:

  • redirectUri: A URI used as a redirection URI in the authorization process.

• authorize(): An asynchronous function that initiates the authorization flow. It must be called at least once to retrieve the access token used during communication with the chatbotChatbot.

• finishAuthentication(): An asynchronous function used to exchange the code for a token. It must be called on the page defined in redirectUri. After authentication, it will redirect back to the page from which the authorize() function was called.

• isAuthenticated(): Returns true if the user is authenticated.

• getAccessToken(): Returns an access token used in chatbot Chatbot communication.

Usage Examples

First, create an HTML structure with a container and form to view messages and send new messages:

<div id="chatbot-wrapper">
  <div id="chatbot-container">
    <div id="messages-wrapper">
      <div id="messages-container"></div>
    </div>
    <form id="message-form">
      <input
        type="text"
        id="message-input"
        placeholder="Enter your message"
        required
      />
      <button id="send-button" type="submit">Send</button>
    </form>
  </div>
</div>

...

This HTML and CSS will be used for both public and internal chatbotsChatbots.

Public Chatbot

Create a script of type="module" that will handle communication with the chatbot Chatbot as well as rendering of messages.

First, import the code snippet:

import { ChatbotClient } from "./chatbot_client.js";

Create an instance of ChatbotClient and start communication:

const chatbotClient = new ChatbotClient();
chatbotClient.connect();

Define variables that will help with rendering messages:

let currentMessageSpan = null;
const messagesContainer = document.getElementById("messages-container");

Define a function that will handle incoming messages and attach it to chatbotClient:

chatbotClient.onMessage = onMessage;
function onMessage(messageData) {
  if (messageData.state === "processing") {
    currentMessageSpan.textContent += messageData.message;
  }
}

Add code responsible for sending new messages:

window.addEventListener("DOMContentLoaded", function () {
  const form = document.getElementById("message-form");
  const messageInput = document.getElementById("message-input");
  form.addEventListener("submit", (event) => {
    event.preventDefault(); // Prevent form submission
    const message = messageInput.value;

    // Display sent message
    const sentMessageDiv = document.createElement("div");
    sentMessageDiv.className = "message sent";
    sentMessageDiv.textContent = message;
    messagesContainer.appendChild(sentMessageDiv);

    const currentMessageDiv = document.createElement("div");
    currentMessageDiv.className = "message received";
    currentMessageSpan = document.createElement("span");
    currentMessageDiv.appendChild(currentMessageSpan);
    messagesContainer.appendChild(currentMessageDiv);

    chatbotClient.sendMessage(message);
    messageInput.value = "";
  });
});

Internal Chatbot

Most of the code for the internal chatbot Chatbot is the same, so only the code unique to the internal chatbot Chatbot will be provided in this section. The difference is that the authentication part needs to be added. This can be done either using the AuthenticationService class included in the code snippet or, if the user already has a token accepted by the Personal AssistantAgent, it can be directly passed to the connect method. An example of this might be when the Personal Assistant Agent and the web page are configured with the same Entra ID application for authentication.

Using AuthenticationService

Import AuthenticationService from the code snippet:

import { ChatbotClient, AuthenticationService } from "./chatbot_client.js";

Create an instance of AuthenticationService and initialize it by providing the redirect URI:

const authService = new AuthenticationService();
authService.init(`${window.location.origin}/login`);

Initiate the authorization flow if the user is not yet authenticated:

if (!authService.isAuthenticated()) {
  authService.authorize();
}

This will redirect the user to the authorization endpoint that the Personal Assistant Agent uses to authenticate users. Once the user provides their credentials and successfully logs in, they will be redirected to the page defined in the redirect URI with an authorization code and state that will be used to retrieve the access token.

Create a page for redirection (this is the page that the redirect URI points to). This page needs to contain the following piece of code:

<script type="module">
  import { AuthenticationService } from "../chatbot_client.js";
  const authService = new AuthenticationService();
  await authService.finishAuthentication();
</script>

...

Pass the access token to the connect function:

chatbotClient.connect(authService.getAccessToken());

Example implementations

The attached ZIP archives contain minimal chatbot Chatbot integrations following the guide above. Each of them requires supplying your own chatbot_client.js, after which they will be fully functional and can be used as reference for you to integrate the chatbots Chatbots into your own apps.

...