Widget

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

Zero-install (recommended): load hosted chat.js from your ChatAI deployment — no npm package required.

Programmatic embed: install @nightzeros/chatai-widget or @nightzeros/chatai-react from npm when you need mountWidget / <ChatWidget /> in your bundler (see React). The hosted IIFE is not published to npm.

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

Hosted script (recommended)

Load chat.js from your ChatAI origin. Production hosted URL:

<script
  src="https://app.nightzeros.com/widget/chat.js"
  data-assistant-id="asst_your_public_id"
  async
></script>

Self-hosted ChatAI instance:

<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.

Voice (preview)

When the assistant owner turns on Offer Voice in the public widget (assistant Settings → Privacy) and the instance has a Voice provider configured, the widget shows a microphone button next to the message box. Visitors can switch between typing and speaking in the same conversation.

• Answers come from the same Purpose, instructions and Knowledge as text chat; provider keys never reach the browser.
• Voice needs HTTPS (or localhost), microphone permission and WebRTC. Otherwise the widget explains why and text chat keeps working.
• The Voice bar shows Not saved, Voice transcript not saved or Recording depending on the assistant's privacy settings. Recording always asks the visitor to Agree and start first.
• Hide Voice on a page with data-voice="off".
• Voice plays only speech ChatAI has approved (the playback gate). The hosted chat.js supports it; the npm @nightzeros/chatai-widget needs 1.2.0 or later, and older versions get Voice needs an updated chat widget.

Setup, recordings, consent, usage minutes and troubleshooting: Voice (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