chatgram-widget

chatgram-widget

The Chatgram customer messenger for any website: real-time live chat with your team (answering from Telegram, Slack or the browser), instant AI answers, and the classic email contact form — in one dependency-free script.

• Live chat or email, decided per site — the server tells the widget which experience a site runs (mode: "auto"). Sites that stay on email get the v1.1 contact form, unchanged.
• Real-time — Server-Sent Events with automatic reconnect, polling fallback, offline outbox and cross-tab sync. Messages are never lost when the connection drops.
• AI that already knows your business — when you add a website, Chatgram reads it and writes the AI's knowledge base for you, and AI answers are on from day one. Nothing to configure in the widget.
• AI + humans — AI answers with typing stages, product cards and suggestion chips, one-tap "Talk to a person", waiting line, email follow-up when the team is away.
• Polished — home screen with team presence, read receipts, typing indicators, attachments (drag & drop, paste), image lightbox, ratings, transcripts, sounds, unread badges and previews.
• Safe in any theme — Shadow DOM, no external fonts or CDNs, works at 320 px, full-screen on phones, keyboard and screen-reader friendly, prefers-reduced-motion, RTL.
• Zero dependencies, ESM + CJS + UMD, TypeScript types, SSR-safe.

Quick start (any website)

This package is for every site that isn't on WordPress or Shopify (those have their own plugin and app): plain HTML, React / Next.js, Vue, Svelte, Webflow or Framer custom code, web apps.

1. Add your website. Sign in at chatgram.brandid.app, click + Add Website, enter your domain and publish the DNS TXT record it shows, then click verify.
2. Add the widget with the script tag or npm install below. Pass the site's public key (shown on your website's page in the dashboard), or nothing at all: without a key the widget uses the page's domain.
3. That's it. Chatgram reads your website and writes what the AI knows in the background — usually within a few minutes. Connect Telegram or Slack in the dashboard to get chats on your phone.

AI auto-responses, out of the box

New websites start with:

While the knowledge base is still being written — or when the AI is off or outside the hours you gave it — the widget hides the "answers instantly" hint and conversations go to your team, so visitors never meet an AI that doesn't know your business yet. The widget picks this up live (team.aiAvailableNow on the realtime stream): no reload, rebuild or redeploy needed.

Everything else lives on one page per website in the dashboard, under AI Assistant: one switch to turn the AI on or off, when it answers (always, when nobody's online, outside business hours, on a schedule, or after a wait), what it knows (rebuild from your website, add to it, or edit it by hand), a "try a question" box, and blocked senders, where you can unblock an email address.

The assistant's name is set in the dashboard; the widget's AI copy can be changed with texts (for example aiHint, aiSubline, aiThinking).

Install

npm install chatgram-widget

or drop in the script (auto-initialises from data attributes):

<script src="https://cdn.jsdelivr.net/npm/chatgram-widget@2/dist/chatgram-widget.umd.js"
        data-public-key="YOUR_PUBLIC_KEY" async></script>

Supported attributes: data-public-key, data-domain, data-api-base-url, data-mode (auto|live|email), data-display (floating|inline), data-container, data-source, data-position (bottom-right|bottom-left), data-color, data-tooltip, data-bottom-offset, data-side-inset, data-open="true". An explicit ChatgramWidget.init() call always wins.

Usage

import { init, on, open, identify } from 'chatgram-widget';

init({
  publicKey: 'YOUR_PUBLIC_KEY', // or domain: 'example.com'
  theme: { primaryColor: '#4F46E5' },
});

identify({ name: 'Jamie Rivera', email: 'jamie@example.com' }); // signed-in users
on('message', ({ message }) => console.log('New reply:', message.text));
document.querySelector('#help').addEventListener('click', () => open());

Inline (contact page)

init({ publicKey: 'YOUR_PUBLIC_KEY', display: 'inline', container: '#chat' });

The container decides the size (e.g. #chat { height: 640px }).

React

useEffect(() => {
  init({ publicKey: 'YOUR_PUBLIC_KEY' });
  return () => destroy();
}, []);

Vue

onMounted(() => init({ publicKey: 'YOUR_PUBLIC_KEY' }));
onBeforeUnmount(() => destroy());

API

Events

ready { mode } · mode-change { mode } · language-change { language, dir } · open · close · message { conversationId, message } · message-sent · conversation-started { conversation } · unread { count } · theme-change · email form: submit · success · error · state-change.

Config

All v1 options still work (apiBaseUrl, domain, publicKey, theme, texts, showNameField, showTriggerButton, triggerPosition, triggerBackgroundColor, triggerTextColor, triggerTooltip, triggerIconUrl, zIndex, closeOnEscape, closeOnOverlayClick, maxMessageLength, enableHoneypot, minSubmitDelay, rateLimitMax, rateLimitWindow, requestTimeout, retryAttempts, autoResetDelay, enableDeliverabilityGuide, defaultEmail, defaultName, onSubmit, onSuccess, onError, onOpen, onClose, …) and apply to the email contact form exactly as in 1.x.

theme keys: primaryColor, secondaryColor, backgroundColor, headerBackgroundColor, headerTextColor, textColor, inputBackgroundColor, inputTextColor, inputPlaceholderColor, borderColor, borderRadius, modalBorderRadius, fontFamily, boxShadow. A full, contrast-checked palette is derived from primaryColor (or the brand accent from your Chatgram settings).

texts: every string can be overridden — see DEFAULT_TEXTS in src/core/texts.ts. Values equal to the English defaults are ignored, so they never hide the site's language; use textsByLanguage for per-language wording.

Languages & right-to-left

The widget speaks 117 languages (every text of the messenger, the contact form and the emails your visitors get). The language comes from the site's setting in the Chatgram dashboard (or language / data-language="fa"); visitors can switch from the widget when the site allows it, and their choice is remembered. Right-to-left languages (Persian, Arabic, Hebrew, Urdu…) mirror the layout; names, emails, order numbers and English words inside a right-to-left sentence keep their order (Unicode isolates + dir="auto" on every message). Dates and numbers use the widget language.

ChatgramWidget.init({ publicKey: 'pk_…', language: 'fa' });
ChatgramWidget.setLanguage('en');  // later, e.g. from your own language menu

How it works

1. init() asks POST /api/live-chat/v1/boot which mode the site runs. The answer is cached per site, so the correct launcher paints instantly on the next page view (stale-while-revalidate). If the server can't be reached in time on a first visit, the email form is shown.
2. In live mode the messenger keeps a realtime stream (GET /api/live-chat/v1/stream, SSE) while a conversation is open or the panel is visible, re-syncs on every reconnect, falls back to polling, and pauses when idle.
3. Visitor identity (visitorId + visitorToken) is stored in localStorage per site (memory fallback when storage is blocked).

Build

npm install
npm run build        # dist/: umd (minified), unminified .js, esm, cjs, types
npm run typecheck

dist/chatgram-widget.umd.js is what the WordPress plugin and the Shopify theme extension ship; dist/chatgram-widget.js is the same bundle unminified.

Testing

test/mock-server.mjs is a plain-Node implementation of the visitor API (boot, SSE stream, AI typing stages + answers with products and suggestions, human hand-off, receipts, end/rating, heartbeat with a proactive message, uploads, /api/tickets, an email-mode site, error injection). Open http://localhost:4455/page.html after npm run mock to try the widget by hand.

npm test                 # SSE parser unit test
npm i -D playwright && npx playwright install chromium
npm run test:e2e         # 20+ end-to-end scenarios, screenshots in test/.screenshots/

What's new in 2.1

• 117 languages for the messenger, the contact form and visitor emails; right-to-left layout and correct mixed-direction text. New language, allowLanguageSwitch, textsByLanguage, setLanguage() / getLanguage(), the language-change event and data-language.

What's new in 2.0

2.0 turns the contact form into a full live-chat messenger. Sites that stay on email keep the 1.x form.

• Live chat with your team answering from Telegram, Slack or the browser, in real time.
• AI answers with typing stages, product cards and suggestion chips, hand-off to a person, and the automatic knowledge base described above. The widget follows each site's AI availability live.
• Home screen with team presence, conversation history, read receipts, typing indicators, attachments, ratings, transcripts, sounds and unread badges.
• display: "inline", identify(), startConversation(), getMode() and new events (message, unread, mode-change, conversation-started, …).

Upgrading from 1.x: your init() options keep working. With the default mode: "auto", sites switched to live chat in the dashboard get the messenger and the rest keep the contact form; pass mode: "email" to always keep the form. Script tags that load chatgram-widget without a version pick up 2.0 automatically; pin chatgram-widget@1 to stay on 1.x.

License

MIT © brandID