Integrate a Microsoft Copilot Chatbot with MkDocs

In this post I’d like to show you how to integrate a custom Microsoft Copilot Studio Chatbot with MkDocs. The goal is to provide a chatbot on all pages of the documentation, that is trained with the content of the documentation, see screenshot.

About this Approach

You can connect to a copilot with a custom canvas that is hosted as a standalone web app in your MkDocs project. This option is best if you need to embed a customized iFrame across multiple web pages / documentation pages. Note that the depicted example uses the Material theme and integrates the chatbot by extending the theme.

This post also covers the following customizations to the chatbot`s look and feel:

change the text displayed in the banner
change the color of the banner
add a close button to the banner
add a scaler to the banner (upper left corner) to resize the chatbot
add a button to open the chatbot on multiple documentation pages

Default Chatbot:

chatbot

Customized Chatbot:

chatbotV2

Setup in Copilot Studio

Create a new Copilot chatbot in Copilot Studio, see Microsoft Documentation: Create and Deploy a Copilot Studio Copilot.
Train the Copilot with your published MkDocs website. Note that there are requirements for some URLs, see Microsoft Documentation: URL type and structure.
Optional: Customize Icons, answers, etc, see Microsoft Documentation: Change the copilot name and icon.
Thoroughly test your chatbot in Copilot Studio.
Publish the chatbot, see Microsoft Documentation: Publish your Copilot.
Copy the token endpoint of your chatbot, see Microsoft Documentation: Retrieve token endpoint. The token is needed to integrate the chatbot to your website.

You can add the created chatbot as-is to your website using a simple code snippet, see Microsoft Documentation: Add your Copilot to your Website. To further customize the chatbot and add buttons to open and close the chatbot to your website, follow the instructions in the next paragraph.

Integrate the Chatbot

To customize the default chatbot, we connect the copilot with a custom canvas that is hosted as a standalone web app.

Copy and paste the HTML code provided by the Microsoft Documentation: Customize the Default Canvas and save it as a chatbot.html file in the /docs directory of your MkDocs project.
Open the chatbot.html file and replace <COPILOT TOKEN ENDPOINT> with your token endpoint, see Setup in Copilot Studio.
```
const tokenEndpointURL = new URL('<COPILOT TOKEN ENDPOINT>');
```
Delete the following lines to remove the banner from the chatbot:
```
<div id="banner">
<h1>Contoso copilot name</h1>
</div>
```
This removes the banner from the chatbot. We will create our own banner that includes a scaling option and a close button later.
Test the chatbot integration (token endpoint) by serving the project. You should be able to access and interact with the chatbot via http://localhost:8000/chatbot.html.
If the chatbot works as expected, publish your MkDocs project. This step is necessary to make the custom canvas accessible online.
If it does not exist yet, create a folder /overrides in the root directory of your MkDocs project and create a file main.html, see Material: Extending the Theme.
Adding the chatbot in main.html makes the chatbot available on all pages of the documentation. Alternatively, create a new html template that you can assign to specific pages.

Copy and paste the following code into main.html:

{% extends "base.html" %}

{% block extrahead %}
<link rel="stylesheet" href="{{ 'assets/stylesheets/chatbot.css' | url }}">
{% endblock %}

{% block scripts %}
{{ super() }}
<script src="{{ 'assets/javascripts/chatbot.js' | url }}"></script>
{% endblock %}

{% block content %}
{{ super() }}

<!-- Open Chatbot button -->
<button class="btn-clear md-button" title="Open Chatbot" id="open_button" onclick="openChatbot()">
<span class="twemoji" style="font-size: 35px";"><div class="fa-beat" style="margin-top: -5px;">{% include ".icons/fontawesome/solid/comments.svg" %} </div></span></button>

<!-- Chatbot Container -->
<div id="container" style="display: none;">
    <iframe id="chatbot_iframe" src="https://your-documentation.com/chatbot.html" frameborder="1" style="width: 100%; height: 100%;"></iframe>
    <div id="resize-handler"></div>
    <div id="banner"">
        <p style="font-family: inherit; font-size: 16px; color: white; line-height: 20px; position: absolute; left: 15px;">Theo Chatbot</p>
        <button id="close_button" onclick="closeChatbot()" title="Close Chatbot" style="position: absolute; right: 10px; color: white"><span class="twemoji" style="font-size: 20px">{% include ".icons/material/close.svg" %} </span></button> 
    </div>
</div>
{% endblock %}

Replace the source of the chatbot iFrame (https://your-documentation.com/chatbot.html) with the URL of your published custom canvas.
Download the following files and add them to your MkDocs project:
- chatbot.css
- chatbot.js
The depicted sample references the chatbot.css and chatbot.js files in the main.html file. Depending on where you place the files in your project, you need to adjust the following lines in the main.html file:
```
<link rel="stylesheet" href="{{ 'assets/stylesheets/chatbot.css' | url }}">
```
```
<script src="{{ 'assets/javascripts/chatbot.js' | url }}"></script>
```
Serve or build the project. The button that opens the embedded custom canvas should be displayed at the bottom right corner of the screen.

Customize the Chatbot

Alter this file to better suit your overall design.

Change the Text in the Banner

To change the text in the chatbot banner, modify the following lines in the main.html file:

<p style="font-family: inherit; font-size: 16px; color: white; line-height: 20px; position: absolute; left: 15px;">Theo Chatbot</p>

To change the color of the chatbot banner, modify the following lines in the chatbot.css file:

#banner{
	position: absolute;
	top: 0;
	left: 0;
	width: 100%;
	height: 52px;
	background-color: #ED1A33;
	align-items: center;
    display: flex;
}

Change Color of the “Close” Button

To change the color of the “Close” button in the chatbot banner, modify the following lines in the chatbot.css file:

#close_button {
    position: absolute; 
	right: 10px; 
	color: white;
}

#close_button:hover {
	background-color: #891A33;
	border-color: #891A33;
}

Change Color of the “Open” Button

To change the color of the “Open” button in the chatbot banner, modify the following lines in the chatbot.css file:

#open_button {
    position: fixed;
    bottom: 0;
    right: 0;
    margin: 20px;
    cursor: pointer;
	padding: 10px 20px; /* Adjust padding */
	width: 80px; /* Fixed width for both buttons */
    height: 80px; /* Adjust height */
    border-radius: 40px; /* Rounded corners */
	background-color: white;
	color: #ED1A33;
}
#open_button:hover {
	background-color: #891A33;
	border-color: #891A33;
}

Change Icon of the “Open” Button

To change the icon of the “Open” button at the buttom right corner of the page, modify the following lines in the main.html file:

 <span class="twemoji" style="font-size: 35px";"><div class="fa-beat" style="margin-top: -5px;">{% include ".icons/fontawesome/solid/comments.svg" %} </div></span></button>

Valerie Schipka