Chat Widget JavaScript Embed

Add the ChatSpark Chat Widget to any website with a simple script tag. The widget appears as a floating chat bubble and loads your AI agent automatically.

Quick Start

Add the script tag to your HTML, typically in the <head> or just before the closing </body>. Replace YOUR_ID with your chatbot ID from the ChatSpark dashboard.

html

<script
  src="https://chat.chatspark.io/loader.js"
  data-chatbot-id="YOUR_ID"
></script>

The widget appears automatically as a floating bubble in the bottom-right corner. Users can click it to open the chat and start a conversation.

Configuration Options

You can customize the widget using data-* attributes on the script tag:

Option	Attribute	Description
`chatbotId`	`data-chatbot-id`	Required. Your chatbot ID from the dashboard.
`isOpen`	`data-is-open`	If `"true"`, the chat opens automatically on page load. Default: `false`.
`gaID`	`data-ga-id`	Google Analytics 4 measurement ID for chat event tracking.
`fullScreen`	`data-full-screen`	If `"true"`, the widget renders full-screen instead of as a floating panel.
`render`	`data-render`	CSS selector (e.g. `#my-chat-container`) where the widget mounts. Default: `body`.

html

<script
  src="https://chat.chatspark.io/loader.js"
  data-chatbot-id="abc123"
  data-is-open="false"
  data-ga-id="G-XXXXXXXXXX"
  data-full-screen="false"
  data-render="body"
></script>

Troubleshooting

Content Security Policy (CSP) blocking the script

If you use a strict CSP, add the ChatSpark domains to your policy. The script loads from https://chat.chatspark.io, and the chat iframe connects to your configured API origin.

text

Content-Security-Policy:
  script-src 'self' https://chat.chatspark.io;
  frame-src 'self' https://chat.chatspark.io https://your-api-origin.com;

Script loading order

Ensure the ChatSpark script loads after the DOM is ready. If you load it in the <head>, the widget will mount whenDOMContentLoaded fires. For dynamic SPAs, call openChatSparkBot() or use the ChatSpark API after your app has rendered the target container.

Check the browser console for errors. Common causes: invaliddata-chatbot-id, network failures loading the script, or the target container not existing when the script runs.

Need more control?

See the Controls documentation for programmatic open, close, and toggle, or use the Events API to react to chat activity.

Streaming

Controls