feat(4904): Add WhatsApp widget message prefill support

[anyelopetit]

Summary

Related to hellotext/hellotext#4904. Adds WhatsApp Widget support to hellotext.js using public config key whatsappWidget.

Issue

The Rails app can expose a configured WhatsApp Widget, but hellotext.js needed to load it, pass install-level overrides, and coexist safely with Web Chat when both widgets are enabled.

Root Cause

• hellotext.js only loaded Web Chat from dashboard metadata.
• There was no WhatsApp Widget API client, config model, or DOM model.
• Local install snippets could not override WhatsApp number, body, placement, or launcher icon.
• Widget fetch failures could break initialization instead of failing closed.
• Web Chat and WhatsApp Widget mounted independently without shared stacking classes.

Solution

• Added whatsappWidget config support to Hellotext.initialize.
• Standardized public config on whatsappWidget; no public whatsapp alias.
• Added WhatsApp Widget config validation and JSDoc typedefs.
• Added WhatsApp Widget API client using /v1/widgets/whatsapp/:id.
• Sent install overrides for number, body, placement, and launcher iconUrl as request params.
• Supported custom container mounting and whatsappWidget: false to disable automatic mounting.
• Added WhatsApp Widget DOM model that waits for the Hellotext stylesheet before mounting.
• Missing custom containers no-op with a warning instead of crashing.
• Failed widget HTTP responses, network errors, invalid JSON, and invalid container selectors no-op instead of breaking initialization.
• Added coexistence classes so Rails CSS can stack WhatsApp Widget above Web Chat.
• Added TypeScript definitions, README/docs updates, tests, and rebuilt lib//dist/ artifacts.

Public API

Hellotext.initialize('PUBLIC_BUSINESS_ID', {
  whatsappWidget: {
    id: 'WHATSAPP_WIDGET_ID',
    number: '+15551234567',
    body: 'Hello, I need help'
  }
})

Disable automatic mounting:

Hellotext.initialize('PUBLIC_BUSINESS_ID', { whatsappWidget: false })

Decisions And Trade-Offs

• Used whatsappWidget as the only public config key because whatsapp was never shipped on main.
• Kept server business payload as business.whatsapp because it represents dashboard metadata, not public install config.
• Used CSS class coordination for stacking instead of layout measurement logic.
• Kept local overrides request-local only; they do not persist dashboard settings.

Merge Recommendation

• Release this after the Rails PR is deployed because the SDK fetches /v1/widgets/whatsapp/:id.
• Confirm required approvals and latest Node/Bugbot checks before merge or publish.

Retro-Compatibility

• Existing Web Chat config remains webchat.
• Dashboard metadata can still arrive as business.whatsapp; public install config remains whatsappWidget.
• No public whatsapp alias or WhatsApp strategy option is exposed.
• whatsappWidget: false disables automatic WhatsApp Widget mounting without affecting Web Chat.

Production Risks

• Browser/CDN consumers require the regenerated dist/hellotext.js artifact to be published.
• Runtime behavior depends on the Rails endpoint /v1/widgets/whatsapp/:id being deployed with this SDK release.
• Cached browser/CDN copies may delay rollout until the normal package/CDN invalidation path completes.
• Widget fetch failures now fail closed; watch warnings/errors, but existing Web Chat should keep working.

Pre-Deploy Checklist

• Confirm Rails PR is deployed and /v1/widgets/whatsapp/:id is live.
• Confirm Node 20, Node 22, and Bugbot checks are green.
• Confirm rebuilt lib/ and dist/ artifacts are included.
• Smoke test Web Chat only, WhatsApp Widget only, and both together in all four placements.
• Smoke test whatsappWidget: false, number/body overrides, missing custom container, failed widget response, and Message ?text= behavior.

Post-Deploy Checklist

• Verify package/CDN serves the rebuilt browser bundle.
• Verify a real install snippet with whatsappWidget mounts the widget.
• Verify existing webchat snippets still mount Web Chat.
• Watch for widget endpoint errors or missing-container warnings after release.

Test Verification

• npm run build
• npm test -- --runTestsByPath __tests__/api/whatsapp_widgets_test.js __tests__/core/whatsapp_configuration_test.js __tests__/models/whatsapp_widget_test.js __tests__/hellotext_test.js --runInBand
• node --check src/hellotext.js && node --check src/core/configuration.js && node --check src/core/configuration/whatsapp.js && node --check src/api/whatsapp_widgets.js
• git diff --check

---

Note

Medium Risk
New runtime path depends on the Rails WhatsApp widget endpoint being deployed; failures are isolated but incorrect rollout could leave widgets missing on customer sites.

Overview
Adds dashboard-driven WhatsApp widget support to the browser SDK, mirroring the existing webchat flow.

Hellotext.initialize accepts whatsappWidget (object overrides or false to skip auto-mount). Dashboard metadata from business.whatsapp is deep-merged with install options (number, body for compose prefill, placement, launcher iconUrl, container). A new API client fetches widget HTML from /v1/public/widgets/whatsapp/:id with those overrides as query params; failed fetches, bad JSON, and missing/invalid containers no-op with warnings instead of breaking initialization.

A WhatsAppWidget model waits for the Hellotext stylesheet, mounts into the configured container, and applies stacking classes when webchat is also present. README, docs/whatsapp.md, and TypeScript types document the public API.

^{Reviewed by Cursor Bugbot for commit eff37a8. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit eff37a8. Configure here.}