Widget
Snippet reference
Every option on the script tag, every method on window.DuggAI, in one place.
The script tag
html
<script
src="https://duggai.com/embed.js"
data-key="duggai_pk_XXXXXXXXXXXX"
data-position="bottom-right"
data-theme="auto"
data-locale="en"
defer
></script>Data attributes
| Attribute | Default | Notes |
|---|---|---|
data-key | required | Your public widget key. Starts with duggai_pk_. |
data-position | bottom-right | Also: bottom-left, top-right, top-left. |
data-theme | auto | Also: light, dark. Auto follows the user's OS preference. |
data-locale | en | Determines bot UI strings. See Customization for full list. |
data-suppress | — | If present and truthy, the bubble doesn't auto-show. Use with open() to control visibility from your code. |
data-z-index | 2147483000 | Override only if you have z-index conflicts. |
JavaScript API
The widget exposes window.DuggAI once loaded. The legacy window.DuggSupport alias still works during the rename window — both names resolve to the same object.
identify(user)
Tag the conversation with the signed-in user.
js
window.DuggAI.identify({
id: "u_abc123",
email: "alice@example.com",
name: "Alice Smith",
// optional metadata, sent to the agent for context
traits: { plan: "pro", signupDate: "2025-04-12" },
});For production, use HMAC-signed identify so users can't spoof other accounts.
open() / close() / toggle()
Open or close the bubble programmatically. Useful for "Need help?" buttons.
js
document
.querySelector("#help-button")
.addEventListener("click", () => window.DuggAI.open());sendEvent(name, props)
Push a custom event into the conversation context. The agent sees it on the next message.
js
window.DuggAI.sendEvent("upgrade_plan", {
fromPlan: "free",
toPlan: "pro",
});setContext(ctx)
Set persistent context that's included on every message in the session.
js
window.DuggAI.setContext({
workspaceId: "ws_42",
framework: "next-15",
});logout()
Clear the identify and any session-scoped context. Call when the user signs out.
Events
Listen for widget events on window:
js
window.addEventListener("duggai:opened", () => {
// bubble was opened
});
window.addEventListener("duggai:resolved", (e) => {
console.log("conversation resolved", e.detail.conversationId);
});| Event | Detail |
|---|---|
duggai:loaded | { version } |
duggai:opened | — |
duggai:closed | — |
duggai:message_sent | { conversationId } |
duggai:resolved | { conversationId } |
duggai:escalated | { conversationId, reason } |
Note
The widget loads asynchronously. The loader stubs
window.DuggAI immediately and queues any identify() / setContext() calls — they replay in order once the heavy bundle lands. So calling DuggAI.identify(…) right after the <script> tag is safe.