Widget Customization
The widget is a Preact application bundled as an IIFE and mounted in a Shadow
DOM. Configure it with window.pragenceChatSettings before loading the widget
bundle. The project console's generated code supplies the required widgetKey
and deployment-specific script URL.
Configuration
The runtime accepts these main settings:
| Setting | Purpose |
|---|---|
widgetKey | Required public key for the configured widget |
layout | bubble (default), inline or fullpage |
container | Element or selector filled by inline layout |
position | Bubble position: bottom-right (default), bottom-left, top-right or top-left |
primaryColor | Client-side primary accent color |
greeting, placeholder | Optional overrides for the configured chat copy |
autoOpen, autoOpenDelay | Open the bubble on load and set its delay |
language, dir | UI language and text direction |
voice | Request voice UI when the organization has voice enabled |
userToken, userData | Supply the current user's session and display data |
Example:
<script>
window.pragenceChatSettings = {
widgetKey: "YOUR_WIDGET_KEY",
primaryColor: "#1f2937",
position: "bottom-left",
greeting: "How can we help?"
};
</script>
<script src="https://cdn.pragence.io/widget/v1/pragence-chat.js" async></script>Copy the script URL from the console for your deployment. Bubble, inline and hosted full-page snippets are available from the widget's embed-code controls. For a complete inline example, see Embed Widget.
CSS custom properties
Shadow DOM prevents ordinary host-page selectors from styling widget internals. Inherited CSS custom properties can still set the following values:
:root {
--pragence-font: Inter, system-ui, sans-serif;
--pragence-primary: #1f2937;
--pragence-primary-hover: #111827;
--pragence-primary-light: #eef2ff;
}These properties affect the font, primary message/button color and focus/hover
states. primaryColor can also be set in the JavaScript configuration. The
server-provided widget settings supply the text color, logo and other configured
presentation details.
Public JavaScript API
The bundle attaches PragenceChat to window. It provides init, open,
close, toggle, destroy, sendMessage, setUser and version:
window.PragenceChat.open();
window.PragenceChat.sendMessage("What are your opening hours?");
window.PragenceChat.setUser({ id: "user-123", name: "Sam" });
window.PragenceChat.close();The API dispatches composed DOM events named pragence:open, pragence:close,
pragence:toggle, pragence:sendMessage and pragence:userUpdate. Listen on
the widget container or another ancestor:
document.addEventListener("pragence:open", () => {
console.log("Widget opened");
});
document.addEventListener("pragence:sendMessage", (event) => {
console.log("Requested message:", event.detail.message);
});These events report requests sent to the widget API. For message callbacks, pass
onOpen, onClose, onMessageSent or onMessageReceived in the JavaScript
configuration object when calling PragenceChat.init(config). The event API does
not emit an answer event, and the widget does not expose getHistory, reset
or a Pragence.Widget constructor.
One widget per page
The current bundle uses one fixed container ID and permits one initialized widget per page. If initialized twice, the second initialization is ignored. Create separate widget configurations and keys for separate projects or sites; multiple independent instances on one page are not supported by this bundle.