TomAI Chatbox widget: importable library and CDN embed
npm install tomai-chatbox-widgetbash
npm i tomai-chatbox-widget
or
pnpm add tomai-chatbox-widget
`
Quick Start (Developer Import)
`ts
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)
`html
`
Next.js (App Router) Example
Use a client-only initializer to mount the widget and avoid SSR:
`tsx
// 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:
`tsx
// app/layout.tsx
import dynamic from 'next/dynamic'
const TomaiChatboxClient = dynamic(
() => import('./_components/TomaiChatboxClient'),
{ ssr: false }
)
export default async function RootLayout({ children }) {
return (
{/ ... /}
{children}
)
}
`
Control the widget anywhere in client components:
`ts
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
`bash
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 public
``