JavaScript Embed Features
Custom Actions
React to chatbot events and trigger actions in your host application using the PostMessage API.
Overview
Custom Actions let your host application react to chatbot events and trigger functionality. The embed widget communicates with the parent page using the browser PostMessage API. When the AI sends a message or a user interacts with the widget, your page receives events that you can handle with JavaScript.
Listening for Actions
Add a message event listener on the parent window to receive events from the embed widget: window.addEventListener("message", (event) => { if (event.data.type === "docimal:message") { const { content, role } = event.data.payload; if (role === "assistant" && content.includes("navigate")) { window.location.href = "/pricing"; } } }). This approach lets you trigger any frontend action based on the AI response content.
Execute Code Cards
In your workflows, use Execute Code cards to run custom JavaScript logic during a conversation. This can process user input, call external APIs, compute values, and return structured data back to the workflow. Combine Execute Code cards with Send Message cards to deliver dynamic, action-driven responses to users.
Best Practices
Always verify the event origin matches your Docimal embed URL before processing PostMessage events. Handle errors gracefully — a failed action handler should not crash the chat experience. Use the docimal:message event payload to route actions based on message content or metadata. For complex integrations, consider using the REST API for server-side processing instead of client-side actions.