Widget

The embeddable widget is an IIFE bundle (chat.js) with a Shadow DOM launcher. Copy the exact snippet from the assistant Install tab.

Browser baseline: modern evergreen browsers with Shadow DOM and fetch / streaming support.

Hosted script (recommended)

Load chat.js from your ChatAI origin. The widget derives the API origin from the script URL — do not set data-api-url.

<script
  src="https://your-chatai-instance.example/widget/chat.js"
  data-assistant-id="asst_your_public_id"
  async
></script>

Locally:

<script
  src="http://localhost:3000/widget/chat.js"
  data-assistant-id="asst_your_public_id"
  async
></script>

Self-hosted script

Serve chat.js from your static origin and point API calls at ChatAI:

<script
  src="https://static.example.com/chat.js"
  data-assistant-id="asst_your_public_id"
  data-api-url="https://your-chatai-instance.example"
  async
></script>

From this monorepo:

pnpm examples:prepare-widget
# writes examples/html-widget/chat.js

Open examples/html-widget/self-host.html.

If data-api-url is missing or wrong, the launcher may appear while config/chat fail (CORS, 404, wrong host).

Data attributes

Appearance (colors, position, suggested questions) is controlled from Customize on the assistant and loaded at runtime — keep Customize saved so embeds match the draft preview.

Auth model

Widget chat uses publicId in the request body and no API key. REST SDK access uses Bearer sk_ keys — see API and SDK.

Related

• React
• Examples
• Assistants