Developer Reference Hub

Integration & API Documentation

Fast, production-grade integration recipes for 1ai Brain widgets, stateful vector sessions, and custom LLM routing.

Quick Start Guide

Follow these three simple steps to launch your conversational AI on your website:

Step 1: Register Site

Add your website in the admin dashboard to generate your widget token.

Step 2: Add Origin

Authorize your domain (e.g. https://yourbrand.com) for security.

Step 3: Paste Snippet

Copy the script tag and place before your </body>.

HTML / Vanilla JavaScript Embed

Paste the following script tag into your website template right before the closing </body> tag:

html

<!-- Place this snippet before the closing </body> tag -->
<script
  src="https://1ai-brain.com/widget.js"
  data-token="YOUR_WIDGET_TOKEN"
  async>
</script>

The script loads asynchronously and will not block page rendering or degrade Lighthouse CWV metrics.

React & Next.js Integration

In Next.js (App Router or Pages Router), use the native next/script component with strategy="lazyOnload":

tsx

// React / Next.js App Router (app/layout.tsx)
import Script from "next/script";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://1ai-brain.com/widget.js"
          data-token="YOUR_WIDGET_TOKEN"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

Standalone iFrame Embed

If your platform restricts JavaScript execution (such as certain Notion or Webflow configurations), embed the widget using an iFrame:

html

<!-- Standalone iFrame Embed -->
<iframe
  src="https://1ai-brain.com/widget-frame?token=YOUR_WIDGET_TOKEN"
  width="100%"
  height="580"
  style="border:none; border-radius:20px; box-shadow:0 10px 30px rgba(0,0,0,0.1);"
  allow="clipboard-write"
  title="1ai Brain Assistant"
></iframe>

REST API Integration

For mobile apps, custom backend microservices, or headless chatbots, call the chat endpoint directly with your widget token:

javascript

// Server-to-Server / Custom Integration API
const res = await fetch("https://1ai-brain.com/api/widget-chat", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "x-widget-token": "YOUR_WIDGET_TOKEN",
  },
  body: JSON.stringify({
    sessionId: "user-session-uuid",
    messages: [
      { role: "user", content: "What are your delivery options?" }
    ],
  }),
});

const data = await res.json();
console.log(data.reply);

Widget Configuration Parameters

data-tokenRequired

Type:string

Unique client identification token generated in the dashboard.

themeColor#ea580c

Type:hex / rgb

Primary brand color applied to widget launcher and user speech bubbles.

botName"1ai Assistant"

Type:string

Display name rendered in widget topbar header.

welcomeMessageAuto-generated

Type:string

Initial greeting bubble displayed when visitor opens widget.

Parameter	Type	Default	Description
data-token	string	Required	Unique client identification token generated in the dashboard.
themeColor	hex / rgb	#ea580c	Primary brand color applied to launcher and user speech bubbles.
botName	string	"1ai Assistant"	Display name rendered in widget topbar header.
welcomeMessage	string	Auto-generated	Initial greeting bubble displayed when visitor opens widget.