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.
• 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.
• 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 hellotext/hellotext#5065 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.

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

[cursor]

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

There are 2 total unresolved issues (including 1 from previous review).

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

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