Chat Widget Embed Guide
Add a floating AI chat assistant to any page with a single script tag.
Quick Start
Drop this snippet into your page just before the closing </body> tag:
<script
src="https://talentprism.ai/static/js/chat-widget-loader-bundle.js"
data-team-id="YOUR_TEAM_ID"
data-token="YOUR_EMBED_TOKEN"
></script>
Replace YOUR_TEAM_ID and
YOUR_EMBED_TOKEN with the
values from your TalentPrism account. Both can be found in the
Chat Widget Embed section of your team's white-label settings.
The token is auto-generated when your team is set up.
The widget renders a floating chat icon in the bottom-right corner and opens
an AI-powered assistant panel when clicked.
Data Attributes
| Attribute | Required | Description |
|---|---|---|
| data-team-id | Yes | Your TalentPrism team ID. Found in team settings. |
| data-token | Yes | Embed token for authenticated access. Found in your team's white-label settings under "Chat Widget Embed". Required in production; optional in development. |
| data-base-url | No | Override the TalentPrism host URL. Defaults to the origin of the script src. |
| data-auto-open | No | Whether the chat should automatically open after page load. Defaults to true. |
| data-auto-open-delay-ms | No | Delay before auto-open in milliseconds. Defaults to 2500. |
| data-auto-open-cooldown-hours | No | How long to wait before auto-open can happen again after the widget has been dismissed. Defaults to 168 hours. |
| data-auto-open-scope | No | Which page types are eligible for auto-open: career, all, or job-detail. Defaults to career. |
| data-page-category | No | Page classification used by auto-open targeting: career, job-list, job-detail, or general. Defaults to career. |
| data-welcome-title | No | Overrides the welcome headline shown in the widget home screen. Leave it out and the widget greets
candidates with your AI employee's own name (Hi, I'm <name>!) — rename that employee on the
AI Roster, not in this snippet. |
| data-welcome-body | No | Overrides the welcome copy shown below the title. Defaults to I can help you with your job search, referrals, profile updates, and application questions. |
| data-job-page-url | No | URL of the current job listing page. Defaults to window.location.href. Useful when the widget is in an iframe. |
| data-widget-width | No | Chat panel width in pixels. Defaults to 420 and is capped to fit small screens. |
| data-widget-height | No | Chat panel height in pixels. Defaults to 640 and is capped to the visible viewport. |
| data-launcher-size | No | Floating launcher height in pixels. Icon-only mode uses this as the button diameter. Defaults to 56. |
| data-launcher-variant | No | Launcher display mode: icon, text, or icon-text. Defaults to icon, or text when a launcher label is set without a variant. |
| data-launcher-label | No | Visible launcher text such as Need help?. Used in text and icon-text modes; text mode falls back to Need help? if omitted. |
| data-launcher-color | No | Launcher background. Accepts any CSS background value and defaults to an indigo gradient. |
| data-launcher-hover-color | No | Launcher hover background. Accepts any CSS background value and defaults to a darker indigo gradient. |
| data-launcher-icon-color | No | Launcher chat icon color. Defaults to #ffffff. |
| data-launcher-aria-label | No | Accessible label for the launcher button. Defaults to Open chat. |
| data-bounce | No | Set to true to make the launcher periodically bounce while closed. Defaults to false. |
| data-bounce-interval-ms | No | Duration of each bounce cycle in milliseconds. Defaults to 6000. |
Behavior Notes
Auto-open settings do not control whether the widget loads. They only control how the widget behaves after it has been embedded on the page.
To control where the widget appears, place the script only on the pages where you want the widget to load.
To control where auto-open happens, use data-auto-open-scope together with data-page-category.
SMS verification is the current supported verification method for sensitive widget actions.
JavaScript API
Once loaded, the widget exposes a global window.FleetChat object:
| Method | Description |
|---|---|
| FleetChat.open() | Opens the chat panel. |
| FleetChat.close() | Closes the chat panel. |
| FleetChat.toggle() | Toggles the chat panel open/closed. |
| FleetChat.configure(opts) |
Reconfigures the widget at runtime. Accepts an object with optional keys:
teamId, token,
baseUrl, jobPageUrl,
autoOpen, autoOpenDelayMs,
autoOpenCooldownHours, autoOpenScope,
pageCategory, welcomeTitle,
welcomeBody, widgetWidth,
widgetHeight, launcherSize,
launcherVariant, launcherLabel,
launcherColor, launcherHoverColor,
launcherIconColor, launcherAriaLabel,
bounce, bounceIntervalMs.
The iframe reloads automatically only for settings that affect the embedded assistant URL.
|
Events
| Event | Fires When | Example |
|---|---|---|
| fleet-chat-ready | Widget loader has finished initializing and FleetChat is available. |
window.addEventListener('fleet-chat-ready', cb) |
| Escape key | Pressing Esc closes the chat panel. | Built-in, no code needed. |
Full Example
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Careers — Acme Corp</title>
</head>
<body>
<h1>Open Positions</h1>
<!-- your page content -->
<!-- Custom trigger button (optional) -->
<button onclick="FleetChat.open()">
Talk to our recruiter
</button>
<!-- TalentPrism Chat Widget -->
<script
src="https://talentprism.ai/static/js/chat-widget-loader-bundle.js"
data-team-id="42"
data-token="your-embed-token-from-settings"
data-auto-open="true"
data-auto-open-delay-ms="2500"
data-page-category="career"
data-widget-width="420"
data-widget-height="640"
data-launcher-size="56"
data-launcher-variant="icon-text"
data-launcher-label="Need help?"
data-launcher-color="linear-gradient(135deg, #4f46e5 0%, #7c3aed 100%)"
data-launcher-hover-color="linear-gradient(135deg, #4338ca 0%, #6d28d9 100%)"
data-launcher-icon-color="#ffffff"
data-launcher-aria-label="Open recruiting chat"
data-bounce="true"
data-bounce-interval-ms="6000"
></script>
<script>
// Wait for the widget to initialize, then auto-open
window.addEventListener('fleet-chat-ready', function() {
console.log('Chat widget ready');
// FleetChat.open(); // uncomment to auto-open
});
</script>
</body>
</html>FAQ
Does the widget work on any website?
Yes. The loader script is self-contained and works on any page that can load external JavaScript. It injects its own styles and does not conflict with your existing CSS.
Can I customize the appearance?
Yes. Use data-widget-width, data-widget-height, data-launcher-size, data-launcher-variant, data-launcher-label, data-launcher-color, data-launcher-hover-color, and data-launcher-icon-color. The launcher and panel also use scoped IDs (#fleet-chat-launcher, #fleet-chat-iframe) if a client needs custom CSS overrides.
If I change the defaults, do they affect widgets already live on client sites?
Usually yes, if the client site is loading the current widget loader bundle and has not explicitly set its own values. Explicit data-* attributes on the client site always win over loader defaults. Browser or CDN caching can delay when a changed default shows up.
Where do I find my embed token?
Your embed token is auto-generated and can be found in the Chat Widget Embed section of your team's white-label settings. The token is required in production. Contact your TalentPrism admin if you need it regenerated.
What if I load the script asynchronously?
The loader reads its configuration from the <script> tag's data-* attributes at initialization. Using async or defer is fine — the widget waits for DOMContentLoaded before rendering.
How do I test the integration?
Visit /chat/test/widget-embed/ on your TalentPrism instance for a live sandbox with developer controls.
Can't find what you're looking for?
Contact Us