Documentation

JavaScript Widget

Install the chat widget with the complete code generated in Channels.

The JavaScript widget adds a floating chat bubble to your website. Its generated embed code has two script tags; copy both from your agent's Channels page.

Quick Setup

  1. Open your agent's Channels → Website embed page
  2. Select Chat widget and enable the channel
  3. Copy the complete generated code, including both script tags
  4. Paste it into your website before </body>
  5. Save and refresh your website

The first tag prepares the Agentkit command queue. The second loads the widget with your agent ID and configured script URL. Keep both tags and their values together.

Widget Configuration

Position

The widget appears in the bottom-right corner by default. Change position in Design settings.

Colors

Widget colors match your agent's theme settings. Customize in Design tab.

Mobile

The widget is fully responsive and works on mobile devices automatically.

File Attachments

Visitors can attach documents, spreadsheets, images, and text files directly from the widget. Attachments are used only as temporary conversation context and are not added to your agent's training sources.

Supported uploads include PDF, Word, Excel, HTML, TXT, Markdown, JSON, CSV, PNG, JPG, WEBP, and GIF files. Visitors can attach up to 3 files per message, with a 10MB limit per file. PDFs are parsed up to the first 20 pages to keep responses fast and reliable.

Data Attributes

The widget uses data attributes for configuration:

AttributeDescriptionDefault
data-chatbotRequired. Your agent's ID (included in your embed code)-

Placement

Where to Add the Code

Paste both generated script tags before </body>:

<!DOCTYPE html>
<html>
<head>
  <!-- Your head content -->
</head>
<body>
  <!-- Your website content -->

  <!-- Paste both script tags from Channels > Website embed here -->
</body>
</html>

Single Page Applications

For SPAs, add the complete generated code to your main HTML template or index file.

Multiple Pages

Add the same generated code to every page where you want the widget, or place it in a shared layout template.

Testing Your Installation

After adding the code:

  1. Visit your website in a browser
  2. Look for the chat bubble (bottom-right by default)
  3. Click to open the chat
  4. Send a test message
  5. Verify the response is correct

Troubleshooting

Widget not appearing:

  • Check that both generated script tags appear before </body> in the rendered page source
  • Verify the agent ID is correct
  • Clear browser cache
  • Check browser console for errors

Wrong position:

  • Check Design settings
  • Look for CSS conflicts

Not responding:

  • Ensure training content exists
  • Check plan message limits
  • Test in Playground first

Domain Restrictions

If you've configured allowed domains:

  • Widget only loads on approved domains
  • Other sites see no widget (no error shown)

Configure domains →

Performance

The widget is optimized for minimal impact:

  • Loads asynchronously (async attribute)
  • Small bundle size
  • No render blocking
  • Lazy loads chat interface

Styling Conflicts

The widget uses isolated styles and shouldn't conflict with your site. If you see issues:

  1. Check for global CSS selectors
  2. Look for !important rules
  3. Contact support if problems persist

Removing the Widget

To remove:

  1. Remove both generated script tags from your HTML
  2. Clear any caches
  3. The widget disappears immediately

Next Steps