A lightweight, dependency-free JavaScript SDK for embedding the ECODrIx Chatbot widget into any website or framework — with elegance, speed, and full customization.
The ECODrIx SDK makes it effortless to drop an AI-powered chatbot onto your site.
With a few lines of JavaScript, you can add a floating chat bubble that opens an iframe chat window — beautifully animated, mobile-friendly, and fully customizable.
✅ No dependencies
✅ Works with React, Vue, Next.js, static HTML
✅ Custom bubble colors, tooltips, and icons
✅ Responsive iframe and smooth animations
✅ Auto-open timer & click-outside-to-close behavior
You can install the SDK using npm or a CDN link.
pnpm add @ecodrix/chatbot
npm install @ecodrix/chatbot
Paste this before </body>, with your client code (Settings → Developer, or
Connect → Website chat):
<script src="https://cdn.jsdelivr.net/npm/@ecodrix/chatbot@2/dist/index.global.js" data-erix="CLIENT_CODE" async></script>The widget starts itself. Its name, greeting, colour, side (left/right), logo and business hours come from your Website chat settings in ECODrIx, so you never edit the tag to change them. The bubble stays hidden until those settings arrive (at most 3 seconds), so it never shows the wrong colour.
@2 always serves the latest 2.x release from npm (jsDelivr refreshes a new
release within about 12 hours). To pin a version, use the exact version with
its integrity hash and update the tag yourself to get fixes. For 2.1.0:
<script
src="https://cdn.jsdelivr.net/npm/@ecodrix/chatbot@2.1.0/dist/index.global.js"
integrity="sha384-vV4MKRnFcty5p7WSuSmuenJDCv+vnRFDFdIUju91C0V3pXU9Uoc/C+S7S/GhGh1b"
crossorigin="anonymous"
data-erix="CLIENT_CODE"
async
></script>The hash for a release: curl -s <that URL> | openssl dgst -sha384 -binary | openssl base64 -A.
The same file is on any npm CDN as dist/index.global.js.
Recommended: pass your
clientCode(your public workspace id, from Settings → Developer). The SDK builds the hosted widget URL for you — no need to hand-craftbotUrl. Messages land in your ECODrIx inbox.
import { ECODrIx } from "@ecodrix/chatbot";
ECODrIx.init({
clientCode: "ACME123", // ← recommended; derives the widget URL
bubbleColor: "#4f46e5",
bubblePosition: "bottom-right",
autoOpen: 10, // auto-open after 10 seconds
onOpen: () => console.log("chat opened"),
});A dedicated entry ships a component + hook (React is an optional peer dep):
"use client";
import { ECODrIxChat } from "@ecodrix/chatbot/react";
export default function Layout() {
return <ECODrIxChat clientCode="ACME123" bubbleColor="#4f46e5" />;
}Imperative control via the hook:
"use client";
import { useECODrIxChat } from "@ecodrix/chatbot/react";
function HelpButton() {
const chat = useECODrIxChat({ clientCode: "ACME123" });
return <button onClick={chat.open}>Need help?</button>;
}The component renders nothing (the floating bubble mounts to document.body) and
is SSR-safe — the widget is only created client-side.
Existing two-tag embeds keep working. Use this form when you need the options
below; don't add data-erix as well (one widget per page either way).
<script src="https://cdn.jsdelivr.net/npm/@ecodrix/chatbot@2/dist/index.global.js"></script>
<script>
ECODrIx.init({
clientCode: "CLIENT_CODE",
autoOpen: 8,
});
</script>A colour or side saved in your Website chat settings replaces bubbleColor
and the left/right part of bubblePosition.
ECODrIx.show(); // Open the iframe
ECODrIx.hide(); // Hide the iframe
ECODrIx.destroy(); // Remove the widget completely| Option | Type | Default | Description |
|---|---|---|---|
| clientCode | string |
— | Public workspace id — SDK derives the widget URL (recommended; one of clientCode/botUrl required) |
| baseUrl | string |
"https://console.ecodrix.com" |
ECODrIx app origin used with clientCode |
| botUrl | string |
— | Explicit iframe URL (advanced; optional when clientCode is set) |
| onOpen | () => void |
— | Called when the chat window opens |
| onClose | () => void |
— | Called when the chat window closes |
| bubbleIcon | string |
"💬" |
Emoji, SVG string, or image URL |
| bubbleColor | string |
"#2b4dcb" |
Base color for the chat bubble |
| iconColor | string |
"#ffffff" |
Color for icon inside bubble |
| pulseColor | string |
"#34d399" |
Pulse/ripple effect color |
| tooltipText | string |
"Chat with us!" |
Hover tooltip text |
| tooltipColor | string |
"#333333" |
Tooltip text color |
| tooltipBgColor | string |
"#ffffff" |
Tooltip background color |
| bubbleSize | number |
56 |
Diameter of bubble in pixels |
| bubblePosition | "bottom-left", "bottom-right", "top-left", "top-right" |
"bottom-right" |
Screen corner position |
| iframeWidth | number |
380 |
Width of chat iframe, kept in the viewport |
| iframeHeight | number |
600 |
Height of chat iframe, kept in the viewport |
| iframeBorderRadius | number |
8 |
Iframe border radius in px |
| shadow | string |
"0 25px 50px -12px rgba(0,0,0,0.4)" |
Shadow under iframe |
| bubbleShadow | string |
"0 10px 40px rgba(0,0,0,0.2)" |
Shadow under bubble |
| ripple | boolean |
true |
Enable ripple animation |
| rippleSpeed | number |
1.5 |
Ripple speed multiplier |
| autoOpen | number |
0 |
Seconds before iframe auto-opens |
| closeClickOutside | boolean |
true |
Close iframe on outside click |
import { ECODrIx } from "@ecodrix/chatbot";const chatbot = ECODrIx.init({
clientCode: "CLIENT_CODE",
bubbleIcon: "<svg>...</svg>",
bubbleColor: "#9333ea",
tooltipText: "Need help?",
tooltipBgColor: "#111827",
tooltipColor: "#ffffff",
shadow: "0 15px 40px rgba(0,0,0,0.3)",
autoOpen: 5,
});// Dynamically update configuration
chatbot.updateConfig({
bubbleColor: "#2563eb",
tooltipText: "Chat is live!",
});Use the dedicated @ecodrix/chatbot/react entry (no manual useEffect wiring):
"use client";
import { ECODrIxChat } from "@ecodrix/chatbot/react";
export default function App() {
return (
<>
<YourApp />
<ECODrIxChat clientCode="ACME123" bubbleColor="#4f46e5" />
</>
);
}import { ECODrIx } from "@ecodrix/chatbot";
export default {
mounted() {
ECODrIx.init({
clientCode: "CLIENT_CODE",
bubbleColor: "#4f46e5",
});
},
};<!DOCTYPE html>
<html>
<head>
<title>My Site</title>
</head>
<body>
<script src="https://cdn.jsdelivr.net/npm/@ecodrix/chatbot@2/dist/index.global.js" data-erix="CLIENT_CODE" async></script>
</body>
</html>Under the hood, the SDK:
- Creates a floating bubble button (a labelled button with
aria-expanded; Enter or Space opens the chat and moves focus into it, Esc closes it and returns focus to the bubble) - Preloads the chat iframe for instant open. The chat reads the visitor's thread once; it connects for live replies only when the visitor opens it (or starts typing), so page views without a chat cost one read.
- On phones (screen width up to 480 px) the open chat fills the screen, inside the safe area (notch, home bar), and the page behind it doesn't scroll. Closing restores the page.
- Talks to the chat iframe with
postMessage, trusting only the iframe it opened (its origin and its window):- from the chat:
CHAT_WIDGET_CLOSE, andCONFIG { color, position }with your saved colour and side; - to the chat:
OPENwhen the visitor opens it, andPAGE { path, title }when the chat opens and when the page changes (popstate,hashchange). Only the path is sent, never the query string or hash, which can carry tokens or personal data.
- from the chat:
- Exposes control methods (init, show, hide, destroy) globally or as module exports
It's pure vanilla JavaScript — no React, no external dependencies, no heavy bundle. Perfect for embedding on any platform or CMS.
Released under the MIT License.
Built and maintained by the ECODrIx Team, crafting elegant automation tools for modern businesses.
Ready to enhance user engagement? Install the SDK and start chatting with your visitors in minutes! 🚀