tomai-chatbox-widget
v1.0.5
Published
TomAI Chatbox widget: importable library and CDN embed
Maintainers
nthieu1332002Readme
tomai-chatbox-widget
TomAI Chatbox widget – usable two ways:
- Developer import (npm): programmatically mount into your app.
- CDN embed (script tag): drop-in for any webpage.
Install (npm)
npm i tomai-chatbox-widget
# or
pnpm add tomai-chatbox-widgetQuick Start (Developer Import)
import { initTomaiChatbox } from 'tomai-chatbox-widget'
initTomaiChatbox({
client_id: 'dd650ef8-45e6-4a66-a24f-8752f21f4577',
mode: 'bubble', // 'bubble' | 'fullscreen' | 'popup'
draggable: true
})
// Controls exposed globally for convenience
window.tomaiConfig.open()
window.tomaiConfig.close()
window.tomaiConfig.onToggleModal()
window.tomaiConfig.onFocusMessage()CDN Embed (Script Tag)
<script>
window.tomaiConfig = {
client_id: 'dd650ef8-45e6-4a66-a24f-8752f21f4577',
draggable: true,
// mode: 'bubble' | 'fullscreen' | 'popup'
}
</script>
<script id="chatbox" src="https://aichatbot.softworld.dev/plugins-temp/chatbox-script.js"></script>Next.js (App Router) Example
Use a client-only initializer to mount the widget and avoid SSR:
// app/_components/TomaiChatboxClient.tsx
'use client'
import { useEffect } from 'react'
import { initTomaiChatbox, destroyTomaiChatbox } from 'tomai-chatbox-widget'
export default function TomaiChatboxClient() {
useEffect(() => {
// Guard to avoid double init in dev Strict Mode
if (document.getElementById('sw-customer-chatbox')) return
initTomaiChatbox({
client_id: 'dd650ef8-45e6-4a66-a24f-8752f21f4577',
draggable: true,
mode: 'bubble' // 'bubble' | 'fullscreen' | 'popup'
})
return () => {
destroyTomaiChatbox()
}
}, [])
return null
}Insert the client component at the end of your layout body:
// app/layout.tsx
import dynamic from 'next/dynamic'
const TomaiChatboxClient = dynamic(
() => import('./_components/TomaiChatboxClient'),
{ ssr: false }
)
export default async function RootLayout({ children }) {
return (
<html>
<head>{/* ... */}</head>
<body>
{children}
<TomaiChatboxClient />
</body>
</html>
)
}Control the widget anywhere in client components:
window.tomaiConfig.open()
window.tomaiConfig.close()
window.tomaiConfig.onToggleModal()
window.tomaiConfig.onFocusMessage()Config Options
- client_id: required – your bot key.
- mode: optional –
'bubble'(default),'fullscreen','popup'. - draggable: optional – enable dragging of the launcher bubble.
Notes
- The widget renders inside a Shadow DOM to avoid CSS conflicts.
- It fetches appearance & initial message from the TomAI API based on
client_id. - React is a peer dependency in npm usage; it’s not bundled.
Build & Publish
# Build the library (ES/UMD) and types
pnpm run build:lib
pnpm run build:types
# Optional: build the CDN IIFE script (chatbox-script.js)
pnpm run build:cdn
# Publish to npm (public scope)
npm publish --access publicBranding & Links
- Website: https://tomai.vn
- Repository: https://github.com/softworldvn/tomai-chatbox
- Issues: https://github.com/softworldvn/tomai-chatbox/issues
License
MIT © SoftWorld