The universal install path
If your site renders HTML in a browser, ChatRaj works on it. There is one install path and it takes about 60 seconds.
The chatbot snippet is one line:
<script async src="https://chatraj.com/widget.js" data-bot-id="YOUR_BOT_ID"></script>
Paste it just before the closing </body> tag of your site's HTML. Save the file. Deploy your site (or refresh the page if you're running a dev server). The chatbot bubble appears in the bottom-right corner of every page that includes that HTML.
If you use a static site generator or a templating system, paste the snippet into your shared layout template once and every page picks it up automatically. The "where to paste" section below covers the standard spots for the major frameworks.
That's the whole integration. The widget loads asynchronously after your page renders, never blocks Largest Contentful Paint, and shows up on every page that includes the snippet. No build-step plugin to wire up. No npm package to install. No framework-specific configuration.
Where to paste, by framework
Every static site generator and framework has a "shared layout" file or template that wraps every page. That's the right place for the script tag. Quick reference for the popular stacks:
Hugo. Edit layouts/_default/baseof.html. Paste the script tag just before the closing </body> tag, after the main content block.
Jekyll. Edit _layouts/default.html (or whichever layout you've configured as the default). Paste before </body>.
Astro. Edit src/layouts/Layout.astro (or your custom layout component). Paste inside the <body> slot just before </body>.
Next.js (App Router). Edit app/layout.tsx. Use the Next.js Script component with strategy="afterInteractive" and the script src. Place it inside the <body> element of the root layout.
Next.js (Pages Router). Edit pages/_document.tsx. Use the Next.js Script component inside the <Html><body> block.
Gatsby. Edit gatsby-ssr.js and use the setPostBodyComponents API to inject a script tag. Alternatively, drop the snippet into your shared layout component (src/components/layout.js or similar).
Docusaurus. Add the script via docusaurus.config.js under scripts. Pass { src: 'https://chatraj.com/widget.js', async: true, 'data-bot-id': 'YOUR_BOT_ID' }.
VitePress. Add the script via the head array in .vitepress/config.ts. Use the script entry with { async: '', src: '...', 'data-bot-id': '...' }.
Eleventy. Edit your base layout (often _includes/layouts/base.njk or similar). Paste before </body>.
Plain HTML. Edit every .html file and paste before </body>. (If you have more than a few pages, consider switching to a static site generator with a shared layout. This is unrelated to ChatRaj but will save you future copy-paste pain.)
Custom PHP, Rails, Django, Laravel. Find the shared application layout (app/views/layouts/application.html.erb for Rails, base.html for Django, resources/views/layouts/app.blade.php for Laravel). Paste before </body>.
Why before </body> matters
The script tag is async (it loads in parallel with your page's HTML parsing) AND positioned at the bottom of the body. That combination means:
- Your page's HTML and CSS render first, the visitor sees content immediately.
- The chatbot loader fetches in the background while the rest of the page hydrates.
- The chatbot bubble appears 1-2 seconds after page load, never competing with First Contentful Paint or Largest Contentful Paint.
Putting the script in <head> would still work (the async attribute prevents render-blocking), but the convention for embedded chat widgets is the body-end placement and that's what every developer reviewing your code will expect.
How it actually loads
The widget is split in two: a tiny loader script (~6 KB gzipped) that lives at https://chatraj.com/widget.js, and the full chat UI which is rendered inside an iframe pointing at https://chatraj.com/widget/<your-bot-id>. The iframe lazy-loads only after the visitor clicks the chat bubble, not on initial page load.
This split has two consequences for your site:
- The widget's chat UI (React, conversation state, markdown rendering, voice input, all of it) runs in an iframe with its own document context. It does NOT share your site's CSS, fonts, or JavaScript globals. There is zero chance the widget will style-pollute your site or your site will style-pollute the widget.
- The initial cost on first paint is just the 6 KB loader fetch. The heavier chat UI bundle only loads when the visitor opens the chat. Most visitors who don't open the chat never download it.
For dev teams used to reviewing every dependency, this is the cleanest profile a third-party embed can have: tiny loader, isolated iframe, no shared globals.
Content Security Policy (CSP) considerations
If your site sets a Content-Security-Policy header, the widget needs four directive allowances:
script-src https://chatraj.com(to load the loader script)frame-src https://chatraj.com(to render the iframe)connect-src https://chatraj.com https://api.openai.com(the loader connects to chatraj.com for config and the iframe streams responses; OpenAI is included for direct SSE streaming on enterprise deployments)img-src data: https:(for inline avatar images; only needed if your CSP currently restricts img-src)
If your CSP uses 'self' only, you'll need to add the directives above. We don't require unsafe-inline, unsafe-eval, or any other relaxed CSP modifications. The widget runs in a sandboxed iframe and respects standard CSP semantics.
Subresource Integrity (SRI)
We do NOT publish an SRI hash for widget.js because the loader is intentionally versioned: every visit to chatraj.com/widget.js may serve a slightly newer build with bug fixes or performance improvements. SRI is incompatible with this rolling-release model.
If your security policy strictly requires SRI on every third-party script, the alternative is to vendor the loader: download widget.js to your own static assets directory, generate an SRI hash, and serve it from your domain. The trade-off is that you lose automatic loader updates and need to re-vendor periodically. Most dev teams that initially want SRI on every script accept the rolling-release model once they understand the trade.
Testing locally before deploying
ChatRaj's widget needs to know which sites are allowed to embed it (so a random domain can't steal your bot's quota). Configure this on the Embed tab of your bot's dashboard under Allowed Origins. For local development add http://localhost:3000, http://localhost:5173, http://localhost:8080, or whichever ports your dev server uses. For production add your live domain. The same bot can serve both environments cleanly via this allowlist.
If you forget to add a localhost origin, the widget loads but the chat API rejects messages with a 403 and the dev console shows a clear "Origin not allowed" error. That's the expected security behavior; the fix is one line in your Allowed Origins list.
The widget also respects standard browser dev tools: you can inspect the iframe, view network requests to chatraj.com, and read the loader's source by visiting chatraj.com/widget.js directly. We don't obfuscate or minify the loader's outer flow; the entire thing is reviewable.
CDN, edge, and reverse-proxy setups
If your site sits behind a CDN (Cloudflare, Fastly, Bunny, AWS CloudFront) or a reverse proxy, the chatbot widget works without configuration. The widget loader's network calls go directly from the visitor's browser to chatraj.com, NOT through your origin or your CDN. There's no need to add chatraj.com to your CDN's allowed-origin list, no need to set up a proxy route, no need to configure cache rules.
The only edge case to be aware of: if your CDN aggressively rewrites or strips inline scripts (some over-zealous performance modes do this), the snippet may not survive the rewrite. Cloudflare's Rocket Loader is a common culprit; the fix is to add the script tag to Rocket Loader's exclusion list, or disable Rocket Loader entirely (it's mostly redundant in 2026 since async scripts already optimize well in modern browsers).
For teams running Cloudflare Workers, Vercel Edge Middleware, or similar edge-rendering layers: the widget loader runs in the visitor's browser, not at the edge, so your edge logic doesn't interact with it. The script tag flows through your edge function as ordinary HTML and reaches the visitor's browser unchanged. The same applies to AWS Lambda@Edge and Akamai EdgeWorkers configurations.
Lead capture, voice, language, ungated
The chatbot widget includes lead capture (offers the visitor a way to share their email after 2 messages, configurable), voice input (browser-native, no extra cost), multilingual auto-detect (replies in the visitor's language out of the box), and a CSAT rating prompt after a few messages. All four are on every ChatRaj plan including the free tier. Captured leads flow to a CSV export and a webhook of your choice.
For dev-built sites specifically, the webhook is the most common integration path. Point the webhook at your existing CRM (HubSpot, Salesforce, Pipedrive, Attio), or at a Zapier hook, or at a serverless function in your own stack. The webhook payload is JSON: visitor email, name (if captured), the conversation transcript, the page URL, and the bot ID.
GDPR + cookie consent
ChatRaj never trains models on your visitors' chat logs and never shares visitor data across customers. Each bot is fully isolated by chatbot_id; the only data we store about visitors is a random visitor_id cookie (used to give conversation continuity across page loads) and the messages they send.
For GDPR compliance on EU traffic, ChatRaj signs a Data Processing Agreement (DPA) with every paid customer. Visitor consent for the chat widget should fold into your site's existing cookie consent flow. The widget loader honors a window-level flag (window.chatrajConsent = true) so you can keep the bot hidden until your consent layer fires, then flip the flag to load the chatbot.
Common consent integrations on dev-built sites: Cookiebot, OneTrust, Iubenda, and home-grown consent banners. All four can whitelist ChatRaj's domain or use the window flag pattern.
When you should NOT use ChatRaj on a custom HTML site
A few honest signals that ChatRaj might not be the right fit for your custom site:
- Your site has zero public content (everything is behind authentication). ChatRaj's crawler reads public URLs to build the bot's knowledge base. If there's nothing public, there's nothing to train on.
- You need the chatbot to authenticate with your backend per-visitor (e.g. read the logged-in user's order history). ChatRaj is a content-grounded chatbot for anonymous public visitors, not an authenticated assistant. Function-calling / tools support is on our 2026 roadmap.
- You're building a chatbot for a closed beta with under 50 monthly visitors. At that volume the chatbot's value is hard to justify against your setup time. Focus on driving traffic first via SEO, content marketing, or community building.
For everyone else: the universal install path is real, the loader is dev-team-reviewable in under 10 minutes (open chatraj.com/widget.js in your browser and read the source), and the free tier is enough to confirm the bot's answers are good enough for your site before you spend a dollar.