Integrating Chatbots in third-party applications

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

1 Prerequisites
2 Obtaining the JavaScript Code Snippet
3 Overview of Code Snippets
- 3.1 Public Chatbot
- 3.2 Internal Chatbot
4 Usage Examples
- 4.1 Public Chatbot
- 4.2 Internal Chatbot
  - 4.2.1 Using AuthenticationService
- 4.3 Example implementations

Prerequisites

An instance of Personal Assistant deployed
A server with the third-party web application deployed
Knowledge of web development
Understanding of the PKCE authorization flow (applies only to internal chatbots)

Obtaining the JavaScript Code Snippet

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

Navigate to the Personal Assistant web page.
Go to the Chatbots page.
Click the three-dot menu on the right side of the chatbot one wishes to integrate.
Select Code Snippet.
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.

Overview of Code Snippets

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

Public Chatbot

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

connect(): Establishes a connection with the chatbot.
sendMessage(message): Sends a message to the chatbot. It accepts the following parameter:
- message: The message to be sent to the chatbot.
close(): Closes the connection with the chatbot.

It also exposes three event listeners:

onMessage: Triggered when a new message from the 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 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 chatbots, with the only difference being the connect(token) function, which accepts a bearer access token as a parameter for user authentication.

AuthorizationService is used to authenticate users using the PKCE authorization flow. It defines five methods:

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 chatbot.
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 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>

Add some basic styling:

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

Public Chatbot

Create a script of type="module" that will handle communication with the 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:

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

Add code responsible for sending new messages:

Internal Chatbot

Most of the code for the internal chatbot is the same, so only the code unique to the internal 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 Assistant, it can be directly passed to the connect method. An example of this might be when the Personal Assistant and the web page are configured with the same Entra ID application for authentication.

Using AuthenticationService

Import AuthenticationService from the code snippet:

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

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

This will redirect the user to the authorization endpoint that the Personal Assistant 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:

It calls the finishAuthentication() method, which exchanges the authorization code for a token. Once the token is retrieved, it redirects the user back to the page from which the authorization flow was initiated.

Pass the access token to the connect function:

Example implementations

The attached ZIP archives contain minimal 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 into your own apps.