Website Widget

Add an AI-powered chat widget directly to your website for instant customer support. To deploy the widget for support agents without embedding code on a site, see Chrome Extension.

Capabilities

Capability	Supported
Knowledge Source	✗
Deployment Trigger	✓ Chat conversations
Tool Actions	✓ Send messages

Setup

Go to Deploy
Click Create Deployment
Select your agent
Choose Website Widget as the trigger
Configure appearance and behavior
Click Create

Step 2: Get the Embed Code

After creating the deployment:

Click on the deployment to open settings
Go to the Widget tab
Copy the embed code

Step 3: Add to Your Website

Add the embed code before the closing </body> tag:

<script>
(function(d,w){
  w.DuckieWidget={key:"wgt_cTqeFN4LNFCZORc3"};
  var s=d.createElement('script');
  s.src='https://app.useduckie.ai/widget/embed.js';
  s.async=true;
  d.head.appendChild(s);
})(document,window);
</script>

Replace YOUR_DEPLOYMENT_ID with your actual deployment ID.

Customization

Appearance

Customize the widget to match your brand:

Option	Description
Primary color	Button and header color
Position	Bottom-right or bottom-left
Welcome message	Initial greeting shown to visitors
Placeholder text	Input field placeholder

Behavior

Configure how the widget behaves:

Option	Description
Auto-open	Open automatically after X seconds
Show on pages	Specific pages or all pages
Business hours	Only show during certain hours
Require email	Ask for email before starting chat

Advanced Configuration

JavaScript API

Control the widget programmatically:

// Open the widget
DuckieWidget('open');

// Close the widget
DuckieWidget('close');

// Send a message
DuckieWidget('sendMessage', 'Hello!');

// Set user information
DuckieWidget('identify', {
  email: 'user@example.com',
  name: 'John Doe',
  customFields: {
    plan: 'premium',
    accountId: '12345'
  }
});

Passing Context

Pass contextual information to help the agent:

DuckieWidget('setContext', {
  currentPage: window.location.pathname,
  product: 'Enterprise Plan',
  userId: '12345'
});

Proactive messages

Normally the visitor starts the conversation. With proactive messages your own page code starts it instead — the agent opens with a greeting before the visitor types anything. Use it to offer help on a pricing page, nudge a visitor who has stalled in checkout, or react to an in-app event. Call window.DuckieWidget.trigger(...) from your site:

// Show a fixed opener and reveal a teaser on the launcher.
window.DuckieWidget.trigger({
  message: "Comparing plans? I can help you pick the right one.",
});

Choosing who writes the opener

Mode	Pass	What happens
Fixed message	`message`	Your exact text appears as the agent’s first message right away. The agent stays quiet until the visitor replies, so nudges nobody answers cost nothing.
Agent-generated	`instructions` (omit `message`)	The agent writes the opener itself, using your `instructions` as private context for why the conversation started.

// Let the agent write the opener, given context about why it fired.
window.DuckieWidget.trigger({
  instructions: "Visitor has been on the Enterprise pricing page for 60s.",
  metadata: { plan: "enterprise", page: "/pricing" },
});

Options

trigger(options) accepts:

Option	Type	Description
`message`	string	Verbatim opener shown as the agent’s first message. Selects fixed-message mode. Max 4000 characters.
`instructions`	string	Private context passed to the agent about why the conversation started, used when `message` is omitted. Never shown to the visitor. Max 4000 characters.
`metadata`	object	Extra string key/value context attached to the conversation for the agent. Combined with the page metadata the widget already collects. Non-string values are ignored.
`display`	string	`"open"` opens the widget immediately. Omit it (the default) to show a small teaser on the launcher that opens the conversation when clicked.

trigger() returns a Promise that resolves with the result, including runId and status:

`status`	Meaning
`created`	A new conversation was started.
`suppressed`	The visitor already has a conversation in progress, so the trigger was skipped to avoid interrupting.

Triggering before the script loads

If you might call trigger() before embed.js has finished loading, push the call onto a queue instead — it runs as soon as the widget is ready:

window.DuckieWidget = window.DuckieWidget || { key: "wgt_..." };
(window.DuckieWidget.q = window.DuckieWidget.q || []).push([
  { message: "Need a hand getting set up?" },
]);

Proactive triggers are rate-limited per visitor and use the same agent and origin rules as normal widget chat. A trigger from an origin without an active widget deployment, or for an inactive agent, is rejected.

Best Practices

Strategic Placement

Show on pages where users need help (pricing, checkout, docs)
Consider hiding on landing pages to reduce distraction
Use page-specific welcome messages

Provide Context

Pass user and page context so the agent can personalize responses:

User’s plan or tier
Current page or product
Account information

Set Expectations

Use the welcome message to set expectations:

“Hi! I’m an AI assistant. How can I help?”
Mention response times for complex issues

Example Implementations

Documentation Site

DuckieWidget('init', {
  deploymentId: 'YOUR_ID',
  welcomeMessage: 'Need help with our docs? Ask me anything!',
  position: 'bottom-right'
});

// Pass current doc page
DuckieWidget('setContext', {
  currentDoc: document.title
});

SaaS Dashboard

DuckieWidget('init', {
  deploymentId: 'YOUR_ID',
  welcomeMessage: 'Hi {{user.name}}! How can I help?'
});

// Identify the user
DuckieWidget('identify', {
  email: currentUser.email,
  name: currentUser.name,
  plan: currentUser.subscription.plan
});

Troubleshooting

Check browser console for JavaScript errors
Verify the deployment ID is correct
Ensure the script is loading (check Network tab)

Slow to load

The widget script is loaded asynchronously
Initial load may take 1-2 seconds
Subsequent loads are cached

Styling conflicts

Widget uses Shadow DOM to isolate styles
If issues persist, check for global CSS resets

Integrations

Ticketing

Messaging

Knowledge Sources

Issue Tracking

Capabilities

Setup

Step 1: Create a Widget Deployment

Step 2: Get the Embed Code

Step 3: Add to Your Website

Customization

Appearance

Behavior

Advanced Configuration

JavaScript API

Passing Context

Proactive messages

Choosing who writes the opener

Options

Triggering before the script loads

Best Practices

Strategic Placement

Provide Context

Set Expectations

Example Implementations

Documentation Site

SaaS Dashboard

Troubleshooting

Widget not appearing

Slow to load

Styling conflicts

​Capabilities

​Setup

​Step 1: Create a Widget Deployment

​Step 2: Get the Embed Code

​Step 3: Add to Your Website

​Customization

​Appearance

​Behavior

​Advanced Configuration

​JavaScript API

​Passing Context

​Proactive messages

​Choosing who writes the opener

​Options

​Triggering before the script loads

​Best Practices

​Strategic Placement

​Provide Context

​Set Expectations

​Example Implementations

​Documentation Site

​SaaS Dashboard

​Troubleshooting

​Widget not appearing

​Slow to load

​Styling conflicts

Capabilities

Setup

Step 1: Create a Widget Deployment

Step 2: Get the Embed Code

Step 3: Add to Your Website

Customization

Appearance

Behavior

Advanced Configuration

JavaScript API

Passing Context

Proactive messages

Choosing who writes the opener

Options

Triggering before the script loads

Best Practices

Strategic Placement

Provide Context

Set Expectations

Example Implementations

Documentation Site

SaaS Dashboard

Troubleshooting

Widget not appearing

Slow to load

Styling conflicts