AI chatbot widget documentation.

The AI Chatbot Widget is an embeddable JavaScript component designed to work with existing websites.

Once installed, it provides visitors with a chatbot interface directly on the website.

A typical installation looks like this:

<script
    src="https://cdn.yourdomain.com/widget.js"
    data-agent-id="YOUR_AGENT_ID">
</script>

The website does not need to implement:

• Chat UI components
• Message handling
• AI model communication
• Conversation management
• LLM API credentials
• AI response generation
• Backend AI requests

The website only needs to load the widget.

Everything else is handled by the widget and our remote services.

The widget follows a simple client-to-server communication process.

Visitor opens website
        │
        ▼
Website loads widget.js
        │
        ▼
Widget reads the Agent ID
        │
        ▼
Widget initializes
        │
        ▼
Chatbot interface appears
        │
        ▼
Visitor sends a message
        │
        ▼
Widget sends request to our server
        │
        ▼
Our server processes the request
        │
        ▼
AI model generates response
        │
        ▼
Response is returned
        │
        ▼
Widget displays response

The JavaScript running on the customer's website acts as the client-side component.

The AI processing happens remotely.

The integration consists of a script element similar to:

<script
    src="https://cdn.yourdomain.com/widget.js"
    data-agent-id="agt_12345">
</script>

There are two important parts.

src

src="https://cdn.yourdomain.com/widget.js"

This tells the browser where to download the chatbot widget.

The JavaScript file is hosted by our infrastructure, so the website owner does not need to download, install, or maintain the widget source code.

data-agent-id

data-agent-id="agt_12345"

This identifies the chatbot that should be loaded.

The JavaScript file itself is shared.

The Agent ID determines which chatbot configuration the widget should use.

For example:

Customer A
    ↓
agt_12345

Customer B
    ↓
agt_67890

Both websites can load the same widget.js file while displaying completely different chatbot configurations.

No.

The JavaScript file is shared.

For example:

https://cdn.yourdomain.com/widget.js

is the same file for all integrations.

What changes is the identifier:

data-agent-id="agt_12345"

This allows our server to determine which chatbot should respond to the request.

This approach makes the widget easier to maintain, update, cache, and distribute.

When a visitor opens a website containing the widget:

Step 1 — Browser parses the HTML

The browser encounters the widget script.

<script
    src="https://cdn.yourdomain.com/widget.js"
    data-agent-id="agt_12345">
</script>

Step 2 — Browser downloads the JavaScript

The browser requests:

https://cdn.yourdomain.com/widget.js

The JavaScript is downloaded and executed by the browser.

Step 3 — The widget identifies its configuration

The script reads:

data-agent-id

and obtains:

agt_12345

Step 4 — Widget initializes

The widget validates its configuration and initializes its interface.

Step 5 — Chat interface becomes available

The chatbot launcher/interface becomes available to the visitor.

The website owner does not need to manually create the chatbot button or chat container.

Suppose the visitor writes:

What services do you offer?

The widget captures the message.

It then sends a request to our API.

Conceptually:

Browser
   │
   │ HTTPS request
   ▼
Our API
   │
   ├── Identify chatbot
   ├── Validate request
   ├── Process conversation
   ├── Apply chatbot configuration
   └── Request AI response
        │
        ▼
       AI
        │
        ▼
     Response
        │
        ▼
      Widget

The visitor sees the response inside the chatbot interface.

One of the most important properties of the widget is that private AI credentials are not embedded in the customer's website.

The installation code should never contain:

const API_KEY = "...";

or:

const LLM_SECRET = "...";

The browser is an untrusted environment.

Anything delivered to the browser can potentially be inspected.

Instead, the communication follows:

Website
   │
   ▼
Widget
   │
   ▼
Our API
   │
   ▼
AI model

The widget communicates with our servers.

Our servers handle communication with the configured AI model.

This keeps private provider credentials on the server rather than exposing them to website visitors.

Communication between the widget and our services should occur over HTTPS.

For example:

https://api.yourdomain.com

HTTPS encrypts network traffic between the browser and server while it is being transmitted.

This protects the communication from being trivially observed or modified while traveling across the network.

The website hosting the widget should also use HTTPS.

The Agent ID included in the installation snippet should be considered a public identifier.

For example:

agt_12345

It identifies a chatbot but should not be treated as a secret credential.

Do not use an Agent ID as a password or as proof of authorization.

Server-side validation must still be performed for every request.

The chatbot interface can be isolated from the website using an iframe.

Conceptually:

Customer Website
│
├── Existing website
│
├── Existing CSS
│
├── Existing JavaScript
│
└── Chatbot Widget
      │
      └── Chatbot Interface

This prevents the website's CSS and JavaScript from unnecessarily interfering with the chatbot interface.

For example, a website may have global CSS such as:

button {
    border-radius: 0;
}

Without appropriate isolation, such styles could potentially affect the chatbot.

An isolated interface reduces these conflicts.

The website owner does not need to install:

React
Vue
Angular
jQuery
Node.js
npm packages

just to use the widget.

The website only needs to load the provided JavaScript snippet.

The widget's own implementation and dependencies are handled by the widget itself.

This is one of the main advantages of the embed approach.

The current integration is designed to be simple.

Required

The website should:

• Be capable of including JavaScript.
• Allow external JavaScript resources to load.
• Use a modern web browser for visitors.
• Have access to the internet so the widget can communicate with our services.
• Use the correct Agent ID.
• Use the installation snippet exactly as provided.

Recommended

For the best experience:

• Use HTTPS.
• Keep the widget script in the website's normal HTML.
• Avoid unnecessarily blocking external scripts.
• Ensure the website's Content Security Policy permits the required widget resources.

The simplest installation is:

<script
    src="https://cdn.yourdomain.com/widget.js"
    data-agent-id="agt_12345">
</script>

Place the snippet in the website's HTML.

A common location is near the end of the <body> element:

<body>

    <!-- Website content -->

    <script
        src="https://cdn.yourdomain.com/widget.js"
        data-agent-id="agt_12345">
    </script>

</body>

Save the page and reload it.

The chatbot should then initialize.

The widget is designed to be added to an existing website without restructuring the website.

For example, an existing page:

<!DOCTYPE html>
<html>
<head>
    <title>My Website</title>
</head>

<body>

    <h1>Welcome to my website</h1>

    <p>Website content...</p>

    <!-- Chatbot -->
    <script
        src="https://cdn.yourdomain.com/widget.js"
        data-agent-id="agt_12345">
    </script>

</body>
</html>

No chatbot-specific HTML needs to be created manually.

No chatbot CSS needs to be written manually.

No backend endpoint needs to be created by the website owner.

The widget works naturally with traditional HTML websites.

For example:

index.html
about.html
contact.html
services.html

The script can be included on the pages where the chatbot should appear.

If the chatbot should appear throughout the website, add the script to the shared layout/template used by the site's pages.

The widget does not require the website to be written using a particular JavaScript framework.

A website using ordinary:

HTML
CSS
JavaScript

can load the widget directly.

The website's existing JavaScript and the widget can operate independently, provided that the website's security policies do not block the widget.

The current integration is designed to be framework-independent at the installation level.

However, framework-specific integrations are being prepared.

Upcoming integrations will make installation easier for applications built with technologies such as:

• React
• Tailwind CSS
• Next.js
• Other modern frontend frameworks

The goal is to make the widget feel native to the development environment while retaining the same underlying chatbot service.

For example, a future React integration may allow developers to use a dedicated component rather than manually adding a <script> element.

The underlying chatbot service remains the same.

Some websites use a strict Content Security Policy.

For example:

Content-Security-Policy:
    script-src 'self';

Such a policy may prevent the browser from loading an external widget script.

If the widget does not appear despite using the correct installation code, inspect the browser's developer console.

You may see an error indicating that the widget resource was blocked by CSP.

In that case, the website administrator may need to permit the widget's domains in the relevant CSP directives.

Depending on the implementation, this may include permissions for:

script-src
frame-src
connect-src

The exact directives depend on how the widget resources are loaded.

If the widget does not appear, check the following.

1. Confirm the script exists

Make sure the HTML contains the correct script:

<script
    src="https://cdn.yourdomain.com/widget.js"
    data-agent-id="agt_12345">
</script>

2. Check the Agent ID

Make sure:

data-agent-id

contains the correct identifier.

3. Open browser Developer Tools

Open:

F12

or:

Right click → Inspect

Then open the **Console** tab.

Look for widget-related errors.

4. Check the Network tab

Look for requests to:

cdn.yourdomain.com
api.yourdomain.com

If the script returns:

404

the URL is incorrect or the resource is unavailable.

If it returns:

403

the resource may be blocked or unauthorized.

If the interface appears but messages do not receive responses, check:

1. Internet connectivity.
2. Browser console errors.
3. Network requests.
4. API response status.
5. Agent availability.
6. Session initialization.
7. Website CSP/CORS configuration.

A request such as:

POST /v1/chat

should be visible in the browser's Network panel.

Inspect:

Request URL
Request method
Status code
Response

This usually makes the source of the problem obvious.

400 Bad Request

Usually indicates that the request is malformed.

Possible causes include:

• Missing Agent ID
• Missing message
• Invalid request format
• Invalid session information

401 Unauthorized

The request is not properly authenticated or the session credential is invalid.

403 Forbidden

The server understood the request but refused to allow it.

Possible causes include:

• Invalid access
• Unauthorized domain
• Expired credentials
• Restricted agent

404 Not Found

The requested resource does not exist.

Check the widget/API URL.

429 Too Many Requests

The request rate exceeded an allowed limit.

This can happen when too many requests are sent within a short period.

500 Internal Server Error

An unexpected error occurred on the server.

The website owner should generally not need to modify their frontend code for a genuine server-side 500 error.

If:

localhost

works but the production website does not, compare the environments.

Check:

• HTTPS
• CSP
• domain authorization
• browser console
• network requests
• production URL
• Agent ID
• hosting configuration

A production domain may also be subject to security policies that are not present during local development.

If the chatbot looks incorrect because of the website's CSS, the widget should use its isolation mechanism.

If an iframe is used, the chatbot UI exists in a separate document.

If a Shadow DOM or another mechanism is used, CSS encapsulation should be implemented carefully.

Website developers should generally not need to modify their global CSS to make the chatbot work.

The current JavaScript integration can generally be loaded from the application's HTML entry point or appropriate document/layout mechanism.

The website does not need to convert its React application into a different architecture.

Dedicated React integration support is being prepared to provide a cleaner developer experience.

Tailwind CSS does not inherently prevent the widget from working.

The widget should maintain its own interface styling and isolation.

Developers should avoid attempting to style internal chatbot elements from the host website unless the widget explicitly exposes supported customization mechanisms.

Tailwind-specific integration support is also being prepared.

The same account can potentially use different agents on different websites.

For example:

Company
│
├── Main Website
│     └── Agent A
│
├── Online Store
│     └── Agent B
│
└── Support Portal
      └── Agent C

Each installation uses the appropriate Agent ID.

The JavaScript source remains the same.

Only the configuration changes.

The widget can be installed on multiple pages.

For example:

/
 /about
 /products
 /contact
 /pricing

If the script is included on each page, the chatbot can be available throughout the website.

For websites using a shared layout, it is preferable to place the widget integration in the shared layout instead of manually duplicating the snippet across every page.

The widget should be designed so that it does not unnecessarily interfere with the performance of the host website.

The script should:

• Load asynchronously where appropriate.
• Avoid blocking the main page unnecessarily.
• Keep initialization lightweight.
• Avoid expensive operations during initial page load.
• Load the full chatbot interface only when necessary where supported.
• Avoid modifying unrelated page content.

The chatbot is an external application and therefore requires network communication.

Visitors without an internet connection may not be able to use the chatbot.

The widget relies on standard modern browser capabilities such as:

• JavaScript
• HTTPS
• DOM APIs
• Fetch/network APIs
• iframe support where applicable
• modern browser security mechanisms

Very old browsers may not support all functionality.

For current versions of mainstream browsers such as Chrome, Edge, Firefox, and Safari, the widget should be designed around standard supported web APIs.

The widget should follow a simple security principle:

> Anything running in the visitor's browser must be considered public.

Therefore, the widget should never contain:

LLM provider secret keys
Database passwords
Private API credentials
Server administration credentials
Internal infrastructure secrets

Sensitive processing should happen remotely.

The browser should only receive information required to operate the chatbot.

Website developers should also avoid placing sensitive customer information into chatbot messages unless they understand how that information is processed and stored.

Before publishing the website, verify:

• [ ] The widget script URL is correct.
• [ ] The Agent ID is correct.
• [ ] The website is using HTTPS.
• [ ] The widget is present in the final production HTML.
• [ ] The browser console contains no widget errors.
• [ ] The widget interface appears.
• [ ] A test message can be sent.
• [ ] The AI response is received.
• [ ] The chatbot works on mobile if mobile support is expected.
• [ ] CSP does not block widget resources.
• [ ] The production domain is authorized if domain restrictions are enabled.

After adding the snippet:

Test 1 — Page loading

Open the website normally.

Confirm that the chatbot launcher/interface appears.

Test 2 — Open chatbot

Open the chatbot.

Confirm that the interface loads correctly.

Test 3 — Send a message

Send a simple message such as:

Hello

Confirm that a response is returned.

Test 4 — Refresh

Reload the page.

Confirm that the widget initializes again correctly.

Test 5 — Navigate

Visit another page containing the widget.

Confirm that the widget remains functional.

Test 6 — Mobile

Open the website on a mobile device or use browser responsive mode.

Confirm that the interface is usable.

Test 7 — Production

Perform the same tests on the actual production domain.

When troubleshooting, browser Developer Tools are the most useful starting point.

Console

Look for:

JavaScript errors
CSP errors
CORS errors
widget initialization errors

Network

Look for:

widget.js
chatbot iframe
API requests
session requests
chat requests

Useful information includes:

HTTP status
Request URL
Request method
Response
Request timing

Elements

Inspect the page to confirm that the widget's launcher/container/iframe was actually created.

After installation, the website developer generally does not need to maintain the widget's internal JavaScript.

The external widget can be updated centrally.

The website continues loading:

widget.js

while improvements can be made to the hosted widget.

However, changes to browser security policies, CSP configuration, domain authorization, or the installation API may require action from the website owner.

Because the chatbot is remotely hosted, it depends on network connectivity and availability of the widget/API service.

If the remote service is unavailable:

Website
   ↓
Widget
   ↓
API unavailable

the chatbot may fail to initialize or may display an error state.

The failure should be isolated so that the customer's primary website continues functioning normally.

The chatbot should never be treated as a dependency required for the rest of the website to operate.

The JavaScript embed model provides several practical advantages:

Simple installation

One script can be enough.

No backend development required

The website does not need to create its own AI API.

No AI credentials exposed

AI provider credentials remain outside the browser.

Framework independence

The basic integration does not depend on the website's frontend framework.

Centralized updates

The widget can be updated from its hosted source.

Easy distribution

The same widget script can serve many websites and many chatbot configurations.

A complete basic HTML page can look like this:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">

    <title>My Website</title>
</head>

<body>

    <h1>Welcome</h1>

    <p>
        This is my website.
    </p>

    <!-- AI Chatbot Widget -->
    <script
        src="https://cdn.yourdomain.com/widget.js"
        data-agent-id="agt_12345">
    </script>

</body>
</html>

That is the core integration.

No chatbot HTML needs to be written manually.

No chatbot backend needs to be implemented by the website owner.

No LLM key needs to be added to the website.

At a technical level, the widget is a remotely hosted client-side application.

The host website loads the JavaScript file:

widget.js

The script reads its configuration:

data-agent-id

It initializes the chatbot interface and establishes communication with the chatbot service.

The browser sends user messages through HTTPS.

The remote service processes those requests and returns AI-generated responses.

The widget receives the responses and renders them to the visitor.

The overall flow is:

┌──────────────────────────────┐
│       Customer Website       │
│                              │
│  <script src="widget.js">    │
│            │                 │
│            ▼                 │
│      Chatbot Widget          │
└────────────┬─────────────────┘
             │
             │ HTTPS
             ▼
┌──────────────────────────────┐
│       Chatbot Service        │
│                              │
│   Session / Request Handling │
│             │                │
│             ▼                │
│       AI Processing          │
│             │                │
│             ▼                │
│       AI Model               │
└────────────┬─────────────────┘
             │
             │ Response
             ▼
        Chatbot Widget
             │
             ▼
           Visitor

The critical distinction is that the JavaScript widget is **the interface and client-side communication mechanism**, while the sensitive AI processing and credentials remain on the remote service.

## Do I need to modify my website's source code?

Yes, but only minimally.

You need to add the provided script snippet to your website.

You do not need to build the chatbot yourself.

## Do I need to install npm packages?

No for the basic JavaScript integration.

The widget is loaded remotely.

Framework-specific integrations are being prepared for developers who want a more native integration experience.

## Do I need an API key?

You should use the credentials and identifiers provided by the chatbot platform according to its integration instructions.

Do not place private AI provider credentials in the frontend.

## Is the JavaScript snippet unique for every customer?

The JavaScript file is shared.

The Agent ID is unique to the chatbot/configuration.

## Can I use the same Agent ID on multiple pages?

Yes, if you want those pages to use the same chatbot.

## Can different websites use different chatbots?

Yes.

Each website or chatbot configuration can use its own Agent ID.

## Can visitors see my Agent ID?

Yes. An Agent ID used by browser-side code should be treated as public.

It must not be considered a secret credential.

## Can visitors steal my LLM API key from the widget?

The widget should never contain the private LLM API key.

The LLM credential must remain on the server.

## Does the chatbot require my website to use React?

No.

The basic JavaScript integration is framework-independent.

## Does it work with Tailwind CSS?

The widget is designed to operate independently of the host website's styling.

Tailwind-specific integration support is being prepared.

## Does it work with React?

The basic script can be integrated into a React application's appropriate HTML/layout entry point.

A dedicated React integration is being prepared for a more native developer experience.

## Does the chatbot modify my existing website?

The widget dynamically creates its own interface.

It should avoid unnecessarily modifying the website's existing content, styles, or application logic.

## Can my website's CSS break the chatbot?

The widget should isolate its interface to minimize CSS conflicts.

If the widget uses an iframe, its internal document is separated from the host page's CSS.

## Can I customize the chatbot?

Customization depends on the configuration options exposed by the widget/platform.

Typical configurable areas can include:

• Appearance
• Position
• Name
• Avatar
• Greeting
• Behavior

Use the available configuration options rather than directly modifying the hosted widget source.

## What happens if the visitor has no internet connection?

The widget requires network connectivity to communicate with the remote chatbot service.

Without connectivity, AI responses cannot be retrieved from the server.

## What if the widget stops working?

First check:

1. Browser console.
2. Network requests.
3. Agent ID.
4. Widget URL.
5. CSP restrictions.
6. Production domain authorization.
7. API/service availability.

## What if I get a CSP error?

Your website's Content Security Policy may be blocking the widget.

Allow the required widget, chatbot, and API origins according to the integration requirements.

## What if I get a CORS error?

CORS is enforced by browsers when frontend code communicates across origins.

If a CORS error occurs, check that the chatbot service permits the required origin and that the request is being made through the intended widget/API flow.

Do not attempt to solve CORS by disabling browser security.

## Will installing the widget slow down my website?

The widget necessarily requires downloading external resources and communicating with remote services.

The implementation should therefore minimize initial work, load resources efficiently, and avoid blocking the host page unnecessarily.

For the best performance, use the recommended installation method and avoid loading duplicate widget instances.

## Can I install the widget twice on the same page?

You should normally install it only once per page.

The widget should also protect against accidental duplicate initialization, but duplicate installation should still be avoided.

## Can I put the snippet in the <head>?

Depending on the widget implementation, yes, particularly if the script uses appropriate asynchronous/deferred loading.

The recommended installation location should be followed for the specific version of the widget.

## Can I put it at the bottom of <body>?

Yes. This is a common and simple integration approach.

<body>

    <!-- Website -->

    <script
        src="https://cdn.yourdomain.com/widget.js"
        data-agent-id="agt_12345">
    </script>

</body>

## Do I need to rebuild my website after installing the widget?

For a static website, simply adding the snippet and deploying the updated HTML is sufficient.

For a framework-based application, you may need to rebuild and redeploy the application according to its normal deployment process.

The widget is intentionally designed around one simple principle:

> **Add the snippet, and let the widget handle the rest.**

The website provides the location where the chatbot is displayed.

The widget provides the client-side interface.

The remote chatbot service handles communication and AI processing.

The developer does not need to implement an AI chatbot from scratch simply to make an assistant available on an existing website.

As the platform evolves, framework-specific integrations—including React and Tailwind CSS-oriented tooling—will make the installation experience even simpler for modern web applications while preserving the same straightforward integration model.