Pragence

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:

SettingPurpose
widgetKeyRequired public key for the configured widget
layoutbubble (default), inline or fullpage
containerElement or selector filled by inline layout
positionBubble position: bottom-right (default), bottom-left, top-right or top-left
primaryColorClient-side primary accent color
greeting, placeholderOptional overrides for the configured chat copy
autoOpen, autoOpenDelayOpen the bubble on load and set its delay
language, dirUI language and text direction
voiceRequest voice UI when the organization has voice enabled
userToken, userDataSupply 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.

On this page