Documentation

Getting Started

Setup guides, integration examples, and configuration reference for Kind Robots products.

Overview

Assist is a lightweight, embeddable chat widget that connects your users to an AI assistant powered by your own LLM keys. It renders inside a Shadow DOM for complete style isolation, streams responses via Server-Sent Events, and can call your APIs on behalf of users with built-in confirmation for mutating operations.

Quick Start

Follow these four steps to get your first AI assistant embedded on your site.

1
Create a Project
A project is the container for your assistant. It holds the system prompt, LLM configuration, API manifest, and chat history. Create one from the admin dashboard under Projects.
TipChoose a descriptive name — it appears in the chat panel header.
2
Configure the API Manifest
The API manifest tells your assistant which external APIs it can call. Each endpoint has a method, URL, description, and parameter schema. The AI uses these descriptions to decide when and how to call your APIs.
TipStart with a single GET endpoint to test the flow before adding mutating operations.
3
Add an LLM API Key
Assist is a BYOK (Bring Your Own Key) platform. Add your API key from OpenAI, Anthropic, Google, or a custom provider under API Keys. Keys are encrypted at rest with AES-256-GCM.
TipYou can switch providers or models per project at any time.
4
Embed the Widget
Add a single script tag to your site. The widget auto-initializes, attaches a closed Shadow DOM for style isolation, and connects to your project.
html
```
<script
  src="https://www.kindrobots.ai/kind-robots-assist.js"
  data-project-id="your-project-id"
  data-token="your-token"
  data-api-url="https://www.kindrobots.ai"
  data-mode="bubble"
></script>
```
TipReplace data-project-id and data-token with your own values. Add data-api-url only if your API is on a different domain.

Integration Examples

Script Tag

The simplest integration — drop a script tag into your HTML.

Script Tag

<script
  src="https://www.kindrobots.ai/kind-robots-assist.js"
  data-project-id="proj_abc123"
  data-token="your-token"
  data-api-url="https://www.kindrobots.ai"
  data-mode="bubble"
></script>

Programmatic

Load the script and call init() manually for full control over timing and configuration.

Programmatic

import { init, setContext } from '@kindrobots/assist';

// Set context before init (queued automatically)
setContext({ userId: '42', plan: 'pro' });

init({
  projectId: 'proj_abc123',
  token: 'your-token',
  apiUrl: 'https://www.kindrobots.ai',
  mode: 'bubble',
});

Dynamic Token (SPA)

In a single-page app where the auth token is fetched asynchronously, call setToken() before or after init.

Dynamic Token (SPA)

import { init, setToken } from '@kindrobots/assist';

// Token not available yet — init first
init({
  projectId: 'proj_abc123',
  apiUrl: 'https://www.kindrobots.ai',
});

// Later, after authentication completes
const token = await getAuthToken();
setToken(token);

Complete Example

Here's a full HTML document showing the recommended script placement and configuration. Place the script at the end of the <body> tag, just before </body>.

Complete Integration

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>My Site with Kind Robots Assistant</title>
</head>
<body>
  <h1>Welcome to My Site</h1>
  <p>The chat assistant will appear in the bottom-right corner.</p>

  <!-- Kind Robots Assistant Script -->
  <!-- Place at the end of body, before closing </body> tag -->
  <script
    src="https://www.kindrobots.ai/kind-robots-assist.js"
    data-project-id="your-project-id-here"
    data-mode="bubble"
  ></script>

  <!-- For JWT-authenticated projects, add data-token: -->
  <!-- <script
    src="https://www.kindrobots.ai/kind-robots-assist.js"
    data-project-id="your-project-id-here"
    data-token="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  ></script> -->
</body>
</html>

Configuration Reference

All options can be passed via the init() config object or as data-* attributes on the script tag.

Name	Type	Required	Default	Description
`projectId`	`string`	Yes	`—`	The project ID from your admin dashboard.
`token`	`string`	No	`—`	Bearer token sent with every chat request. Required if the project enforces JWT authentication.
`apiUrl`	`string`	No	`'' (same origin)`	Base URL for the chat API endpoint.
`mode`	`'bubble' \| 'panel'`	No	`'bubble'`	UI mode. "bubble" shows a floating button that opens a popup. "panel" docks a full-height sidebar to the right edge.
`context`	`Record<string, string>`	No	`{}`	Key-value pairs merged into every chat request. Use this to pass user identity, page context, or feature flags to the AI.
`renderers`	`boolean`	No	`false`	When true, API responses with renderers are displayed as sandboxed iframes or React components inside the chat.

Script Tag Attributes

When using the script tag integration, configure the widget with these data-* attributes.

Attribute	Maps To	Example
`data-project-id`	`projectId`	`data-project-id="proj_abc123"`
`data-token`	`token`	`data-token="eyJhbG..."`
`data-api-url`	`apiUrl`	`data-api-url="https://api.example.com"`
`data-mode`	`mode`	`data-mode="panel"`
`data-context`	`context`	`data-context='{"userId":"42"}'`
`data-renderers`	`renderers`	`data-renderers="true"`

JavaScript API

The global KindRobots object exposes these methods.

init(config?: KindRobotsConfig)

Creates the assistant instance. If no config object is passed, reads configuration from data-* attributes on the script tag. Auto-called on DOMContentLoaded when loaded via script tag.

setContext(ctx: Record<string, string>)

Merges key-value pairs into the chat context. Safe to call before init — values are queued and applied when the instance is created.

setToken(token: string)

Sets or updates the bearer token used for chat requests. Safe to call before init — the token is queued and applied when the instance is created.

Troubleshooting

Common issues and how to fix them when embedding the widget.

CORS Configuration

The most common error when integrating the Kind Robots assistant is:

"Error: Unable to reach the server."

This error almost always indicates a CORS (Cross-Origin Resource Sharing) misconfiguration on your API server. When the chat widget running on your website tries to call your API endpoints, the browser blocks the request unless your API explicitly allows requests from your domain.

To fix CORS errors:

1. Add the following HTTP headers to your API server responses:
   - Access-Control-Allow-Origin: https://yourdomain.com (or * for development)
   - Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS
   - Access-Control-Allow-Headers: Content-Type, Authorization

2. Handle preflight OPTIONS requests — browsers send an OPTIONS request before the actual API call to check permissions.

3. If using a framework:
   - Express.js: Use the cors npm package
   - Next.js API routes: Return CORS headers in your API route handlers
   - Flask/Django: Use flask-cors or Django CORS middleware
   - Spring Boot: Use @CrossOrigin annotation or configure global CORS

4. Test your CORS configuration by opening your browser's Developer Console (F12) and looking for red CORS error messages when the widget tries to call your API.

Common Setup Issues

Widget doesn't appear on page:
- Ensure the script tag is placed in the <body> element, not in <head>
- Verify the data-project-id matches your project ID from the Kind Robots dashboard
- Check browser console for JavaScript errors
- Make sure you're using the correct script URL: https://www.kindrobots.ai/kind-robots-assist.js

"Invalid project ID" or authentication errors:
- Double-check the data-project-id value matches exactly (including hyphens)
- If your project requires authentication, ensure data-token="your-jwt-token" is set
- For JWT projects, verify the token is valid and not expired

Widget appears but can't connect to APIs:
- Verify the data-api-url (if set) points to the correct domain
- Check that your API endpoints are defined in the Kind Robots dashboard under API Manifest
- Ensure your API server is running and accessible from your domain
- Test API endpoints directly in a new browser tab to confirm they're reachable

Script loaded before page is ready:
- Place the widget script at the end of your <body> tag, just before </body>
- Or use the defer or async attribute on the script tag

Debugging Checklist

When the widget isn't working correctly, follow this checklist:

1. Open Browser Developer Console (Press F12)
   - Look for red error messages, especially ones mentioning CORS, fetch, or network
   - CORS errors will explicitly say "blocked by CORS policy"

2. Verify Project Configuration
   - Confirm data-project-id in your HTML matches the ID shown in the Kind Robots dashboard
   - Check that your project is marked as "Active" in the dashboard
   - Ensure API endpoints are added to the API Manifest for your project

3. Test API Endpoints Directly
   - Copy an API endpoint URL from your manifest
   - Open it in a new browser tab
   - If you get a CORS error in the console but the API works, the issue is CORS configuration
   - If the API returns a 404 or error, fix the API endpoint first

4. Check Script Placement
   - The script tag must be inside <body>, not <head>
   - Recommended: place it at the end of <body>, just before </body>

5. Verify Network Requests
   - Open Developer Tools → Network tab
   - Try sending a chat message
   - Look for failed requests (shown in red)
   - Click on failed requests to see the error details

6. Test in Incognito/Private Mode
   - Browser extensions can interfere with scripts
   - Open your site in incognito/private browsing to rule out extension conflicts

UI Modes

Assist ships with two display modes, controlled by the mode option.

BubbleDefault

A floating circular button fixed to the bottom-right corner. Clicking it opens a 380×520px chat popup. Ideal for support widgets and knowledge assistants.

Panel

A full-height sidebar docked to the right edge of the viewport. The page content is pushed left automatically. Ideal for internal tools and dashboards where the assistant is a primary interface.

Getting Started

Overview

Quick Start

Create a Project

Configure the API Manifest

Add an LLM API Key

Embed the Widget

Integration Examples

Script Tag

Programmatic

Dynamic Token (SPA)

Complete Example

Configuration Reference

Script Tag Attributes

JavaScript API

Troubleshooting

CORS Configuration

Common Setup Issues

Debugging Checklist

UI Modes

Ready to build?