Widget Embed & Integration Guide

Deploy your assistant to any website using the zero-build hosted script tag or the @webchat/widget npm package.

1. Hosted script tag (Zero build step)

Recommended for standard HTML sites, WordPress, Webflow, Shopify, and static websites.

Copy your embed script from the dashboard under Widget → Embed code and paste it directly before the closing </body> tag:

index.htmlhtml

<script src="https://webchat-ai-widget.vercel.app/webchat-widget.iife.min.js" data-widget-id="YOUR_WIDGET_ID" defer></script>

Custom API Origin Override

If you reverse-proxy the widget API through your own domain to avoid third-party requests, specify data-api-base-url:

index.htmlhtml

<script
  src="https://webchat-ai-widget.vercel.app/webchat-widget.iife.min.js"
  data-widget-id="YOUR_WIDGET_ID"
  data-api-base-url="https://webchat-ai-production-7e84.up.railway.app/api/widget/v1"
  defer
></script>

2. SDK Package (Modern frontend frameworks)

For React, Next.js, Vue, or Vite single-page applications.

Install the lightweight package into your project dependencies:

terminalbash

npm install @webchat/widget

Initialize the widget on component mount and clean up on unmount:

ChatAssistant.tsxtsx

'use client';

import { useEffect } from 'react';
import { init } from '@webchat/widget';

export function ChatAssistant() {
  useEffect(() => {
    const dispose = init({
      widgetId: 'YOUR_WIDGET_ID',
    });
    return () => dispose();
  }, []);

  return null;
}

Load the hosted script using Next.js Script component in root layout:

app/layout.tsxtsx

import Script from 'next/script';

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script
          src="https://webchat-ai-widget.vercel.app/webchat-widget.iife.min.js"
          data-widget-id="YOUR_WIDGET_ID"
          strategy="lazyOnload"
        />
      </body>
    </html>
  );
}

Mount into a custom DOM element instead of document.body:

custom-mount.tsts

import { mount } from '@webchat/widget';

const controller = mount({
  widgetId: 'YOUR_WIDGET_ID',
  host: document.querySelector('#my-chat'), // optional
});

Domain allowlists & origin validation

Restrict which websites are permitted to render your assistant.

WebChat AI validates the browser's Origin header on every public widget request. If a site embedding your widget is not listed in your allowed domains, the backend returns HTTP 403 Forbidden and the widget remains inactive.

domain-matching-rulestext

https://example.com     → allowed
https://shop.example.com  → allowed (via *.example.com)
https://evil.example.net  → 403 Forbidden

Exact host: example.com allows that specific hostname on any port or scheme (http/https).
Wildcard subdomain: *.example.com allows any subdomain like docs.example.com or app.example.com.
Open wildcard: * allows any website to embed the widget (not recommended for production).
Empty allowlist: Upload-only chatbots start with an empty allowlist for security; add your production hostname before going live.

Content Security Policy (CSP)

Configuring host security headers to allow widget traffic.

If your website serves a strict Content Security Policy, add the WebChat AI API origin to your connect-src directive:

CSP Headertext

connect-src 'self' https://webchat-ai-production-7e84.up.railway.app/api/widget/v1;