Skip to content
alzafchat / Developers

Documentation / Integrations

HTML widget

Embed chat in a plain HTML page.

Integration guide

A consumer does not need npm or a framework. The provider builds and serves the versioned browser artifact packages/html-widget/dist/browser/chat-widget-0.1.13.global.js under a chosen public URL. The artifact includes SDK, Echo and Pusher; the consumer includes one script.

html
<div id="chat"></div>
<script src="/assets/chat-widget-0.1.13.global.js"></script>
<script>
const widget = AlzafChat.mount({
  target: '#chat', title: 'Support', height: '620px',
  apiBaseUrl: 'https://chat.example.com/api/chat',
  token: () => getCurrentUserToken(),
  reverb: { key: 'public-app-key', host: 'chat.example.com', port: 443, scheme: 'https' }
});
window.addEventListener('pagehide', () => widget.destroy());
</script>

getCurrentUserToken must be implemented by your host using authenticated identity; never embed a service secret or Reverb secret. Shadow DOM prevents chat styles from changing host styles. Untrusted text is rendered as text, not HTML. destroy removes the mounted host and disconnects its client. Call it before replacing a mount.

Runnable example: build SDK/widget, then pnpm --filter @alzaf/example-html dev. Open port 5174 locally or on LAN. The Node static server serves only the page and versioned widget; it is an example server, not a production web server. Default API/Reverb URLs follow browser hostname. Demo sign-in and bearer token input stay in memory. Choose Shope/Nexzan and customer/seller/admin without copying a token from the terminal. The default dev command passes --demo-login; the server renders data-demo-login="true" only for that explicit flag. Run node examples/plain-html/server.mjs without the flag for the token-only path. NODE_ENV=production with --demo-login exits with an error. The static template defaults to data-demo-login="false" and hides local sign-in.

Local sign-in posts the selected disposable account (for example [email protected]) with public demo password DemoPassword123! to /api/demo/login. The backend additionally restricts that endpoint to local/testing mode. Seed demo accounts first. HTTP 401 means seed/configuration mismatch, 429 means wait, and 403/404 means demo sign-in is unavailable. Never reuse those public credentials for real customer accounts; production widget integration obtains its host-authenticated user token.

See frontend reference for options and feature limits. Laravel Blade can use exactly this script after providing a supported host-authenticated user token and configuring API/channel authorization.

Message cards (product/order sidecars) render through the generic cardView layout with plain text and an HTTPS-only action; the in-thread host renderer registry is React-only. See message cards.

Attachments and emoji are included in the same single script — no npm build and no third-party picker. The widget composer has attach and emoji controls, stages uploads with a removable chip, renders images as previews and PDFs as named download chips, and inserts emoji at the composer caret from the SDK's curated EMOJI_GROUPS. Attachment tiles are siblings after the message bubble in the shared chatStyles, so an attachment-only message has no empty bubble. Upload transport follows the server (proxy, or direct-to-S3 with an automatic proxy fallback), and destroy() also clears composer state along with the connection.

If opening a realtime conversation reports a dynamic require of util, rebuild the widget with its browser config and redeploy the versioned asset. Do not bundle the Node Pusher entry into a browser widget. Verify the generated artifact with pnpm --filter @alzaf-it/chat-widget test:browser after building.