JavaScript Embed Features
Widget Control
Programmatically control the chat widget — open, close, position, and configure it using the PostMessage API.
Overview
The Widget Control API lets you programmatically manage the chat widget from your host application using the browser PostMessage API. Open or close the widget in response to user actions, update the API key dynamically, and listen for widget events.
PostMessage API
Control the widget by posting messages to the iframe window. Send: { type: "docimal:open" } to open the chat window, { type: "docimal:close" } to close it, and { type: "docimal:setApiKey", payload: { apiKey: "dcml_pk_..." } } to update the API key dynamically. The widget sends events back to the parent: { type: "docimal:ready" } when initialized, { type: "docimal:message", payload: { id, role, content, createdAt, sources, isStreaming, feedback } } when a message is sent or received, and { type: "docimal:error", payload: "error message" } when an error occurs.
Widget Positioning
Configure the widget position via the mountChatbot options. The position option accepts "bottom-right" (default), "bottom-left", or "inline". In bottom-right/bottom-left mode, the widget renders as a floating button with a chat window popup (fixed position, z-index 999999). In inline mode, the widget renders directly inside the provided container element at full width and height. Set startOpen: true to show the chat window expanded on page load.
Dynamic Theming
Customize the widget appearance through the theme configuration in mountChatbot or via URL parameters on the embed page. Available theme options: mode ("light", "dark", or "auto"), primaryColor (hex color for accents and user message bubbles), fontFamily (CSS font stack), borderRadius (CSS border radius value), headerStyle ("light" or "colored"), messageStyle ("plain" or "colored"), and inputStyle ("default", "inside", or "rounded"). When using the iframe embed, pass the color parameter as a URL query: ?key=dcml_pk_...&color=%238b5cf6.
Session Persistence
Chat sessions persist across page navigations by default using localStorage. The session data (session ID and message history) is stored with the key "docimal_session_{chatbotId}" and restored automatically when the widget reopens. Set persistSession: false in the options to disable this behavior. Sessions are cleared when the user explicitly starts a new conversation using the reset button in the chat window.