Docs Assistant Embedding

Learn how to embed the Docs Assistant widget on your documentation pages.

Overview

The Docs Assistant is a specialized AI-powered widget designed specifically for documentation pages. It provides instant help to your users by answering questions about your documentation using a full-screen interactive dialog.

Try it now!

Click the button below to see the Docs Assistant in action on this page.

Basic Setup

Getting started with the Docs Assistant widget is simple. Just follow these two steps:

If your docs page loads the assistant inside an iframe, make sure the host page origin is included in your OAuth application's allowed_origins. The widget token endpoint validates this origin before issuing a token.

Step 1: Add the Script

Add the docs-widget.js script to your HTML page with the required configuration. If you load multiple docs widgets, give each script a unique data-instance-id:

<script src="https://widget.companin.tech/docs-widget.js" data-client-id="YOUR_CLIENT_ID" data-assistant-id="YOUR_ASSISTANT_ID" data-config-id="YOUR_CONFIG_ID" data-instance-id="docs-help" data-locale="en"></script>

Step 2: Add a Trigger Button

Create a button or element that calls the widget's open() method:

<button id="help-btn" type="button">Ask Documentation Assistant</button><script>  const handleOpen = (event) => {    console.log('Docs widget opened', event?.context);  };  // Generic event API (returns unsubscribe function)  const unsubscribeOpen = window.CompaninDocsWidget?.on?.('open', handleOpen);  document.getElementById('help-btn')?.addEventListener('click', () => {    window.CompaninDocsWidget?.open();  });  // Cleanup on page unload or SPA route change  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeOpen === 'function') unsubscribeOpen();  });</script>

Examples

Here are some practical examples of how to integrate the Docs Assistant:

Example 1: Basic HTML Integration

<!DOCTYPE html><html lang="en"><head>  <meta charset="UTF-8">  <meta name="viewport" content="width=device-width, initial-scale=1.0">  <title>My Documentation</title></head><body>  <header>    <h1>Product Documentation</h1>    <button onclick="window.CompaninDocsWidget.open()">      Need Help?    </button>  </header>  <main>    <!-- Your documentation content -->  </main>  <script    src="https://widget.companin.tech/docs-widget.js"    data-client-id="your-client-id"    data-assistant-id="your-assistant-id"    data-config-id="your-config-id"    data-locale="en">  </script></body></html>

Example 2: Custom Button with Event Listener

For more control, you can add event listeners to your existing buttons:

// Wait for the widget to loadwindow.addEventListener('load', () => {  const unsubscribeResponse = window.CompaninDocsWidget?.on?.('response', (event) => {    console.log('Assistant response:', event?.data);  });  document.getElementById('help-btn').addEventListener('click', () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  });  window.addEventListener('beforeunload', () => {    if (typeof unsubscribeResponse === 'function') unsubscribeResponse();  });});

Example 3: React/Next.js Integration

In a React or Next.js application:

import React from 'react';export default function Documentation() {  const openDocsAssistant = () => {    if (window.CompaninDocsWidget) {      window.CompaninDocsWidget.open();    }  };  return (    <div>      <h1>API Documentation</h1>      <button        onClick={openDocsAssistant}        className="help-button"      >        Ask Customer Support AI Assistant      </button>    </div>  );}

Configuration Options

The Docs Assistant widget accepts several configuration parameters. Use data-instance-id for deterministic per-instance control when embedding multiple widgets on one page:

Required Parameters

data-client-id: Your unique client identifier from the Companin dashboard
data-assistant-id: The ID of the assistant you want to use
data-config-id: Configuration ID for widget customization

Optional Parameters

data-locale: Language code (default: 'en'). Supports: en, de, es, fr, it, nb, nl, pt, sv
data-dev: Set to 'true' for development mode (connects to localhost:3001)

JavaScript API

Once loaded, the widget exposes a global API for programmatic control. For multi-widget setups, prefer instance registries (CompaninDocsWidgets.get(instanceId)) over only using the latest global reference:

open()

window.CompaninDocsWidget.open();

Opens the Docs Assistant dialog in full-screen mode.

close()

window.CompaninDocsWidget.close();

Closes the Docs Assistant dialog and hides the widget.

Custom Styling

You can style your trigger buttons any way you like. Here's an example of a floating help button:

.my-help-button {  position: fixed;  bottom: 20px;  right: 20px;  padding: 12px 24px;  background: #2563eb;  color: white;  border: none;  border-radius: 8px;  font-weight: 600;  cursor: pointer;  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);  transition: all 0.2s;}.my-help-button:hover {  background: #1d4ed8;  transform: translateY(-2px);  box-shadow: 0 6px 8px rgba(0, 0, 0, 0.15);}

Best Practices

Place the trigger button in a prominent, easily accessible location (e.g., header, floating button)
Use clear, action-oriented button text like 'Ask AI' or 'Need Help?'
Ensure the widget script loads before trying to call its API methods
Keep your client credentials secure - never expose them in client-side code

Troubleshooting

Widget not loading?

Make sure the script is loaded before calling the API. You can check if the widget is available:

window.addEventListener('load', () => {  console.log('Widget loaded:', !!window.CompaninDocsWidget);});

Dialog not opening?

Verify that you provided all required parameters (client-id, assistant-id, config-id) and that they are correct. If multiple widgets are present, make sure each script has a unique data-instance-id.

← Back Next: Overview →