Filament Whatsapp Widget Laravel Package

Getting Started

jeffersongoncalves/filament-whatsapp-widget is a Filament plugin that drops a floating WhatsApp contact button onto a panel. It wraps the standalone jeffersongoncalves/laravel-whatsapp-widget package and exposes it as a Filament plugin, so most day-to-day work happens through panel configuration rather than raw Blade.

Minimal path:

1. composer require jeffersongoncalves/filament-whatsapp-widget

2. Register the plugin on the panel(s) you want it on, in your PanelProvider:

   ->plugin(WhatsappWidgetPlugin::make())
   

3. Publish the config so you can set the destination number:

   php artisan vendor:publish --tag="filament-whatsapp-widget-config"
   

4. Set the phone number (E.164 digits, no +, no spaces) and clear config cache with php artisan config:clear.

Where to look first:

• The published config file — this is where number, message, position, and visibility defaults live.
• The plugin class itself (WhatsappWidgetPlugin) for the fluent setters available to you.
• The package's resources/views and lang directories — the lang directory is what changed in 1.4.0.
• composer.json of the package to confirm which version of laravel-whatsapp-widget it pulls in.

First useful use case: a customer-facing panel where the support team wants a one-click "chat with us on WhatsApp" affordance with a pre-filled message like "Hi, I need help with my order #". That's a five-minute integration and is where most teams stop.

Implementation Patterns

Per-panel, not global. Register the plugin only on panels where it makes sense. Admin panels rarely want a customer support button; a customer portal does. If you have both, register on one and leave the other alone rather than relying on runtime visibility checks.

Visibility rules. Gate the widget on authentication state, a feature flag, or a tenant setting using the plugin's conditional methods (or ->visible(fn () => ...) style closures where exposed). A common pattern is showing the widget to authenticated customers but hiding it during impersonation, when the "you're talking to support" premise breaks.

Pre-filled message as context carrier. The button's value is the deep link, not the bubble. Set the message dynamically per page/per record — e.g. include the order number, the product SKU, or the current URL — so the support agent opens the conversation already knowing what the user was looking at. This usually means bypassing the static config and configuring the plugin in a service provider or panel boot() where you can read route parameters.

Localization. As of 1.4.0 the package ships az, hi, ru, uk, uz, zh_CN alongside the existing locales. Use the app's locale (app()->getLocale()) and publish the lang files if you need to change the tooltip/aria label wording. Keep the pre-filled message itself out of the package lang files — it's your copy, not the package's; put it in your own lang/*/whatsapp.php and resolve it at render time.

Multiple buttons / multiple numbers. Sales vs support, or per-region numbers. Register more than one instance with distinct config, or use the underlying package's component directly in a Blade view outside Filament for marketing pages. Don't try to make one instance do routing logic internally.

Outside Filament. The base laravel-whatsapp-widget package can be rendered in plain Blade. If your landing page is not a Filament panel, use that layer and reserve the Filament plugin for the panel.

Testing. Assert the widget's presence/absence per panel using Filament's panel testing helpers, and assert the generated wa.me URL contains a correctly URL-encoded message. That URL is the only thing that actually matters to the end user.

Gotchas and Tips

The dependency bump is the real 1.4.0 change. The plugin now requires laravel-whatsapp-widget: ^2.0 (previously ^1.0). If you pin or indirectly constrain the base package to 1.x anywhere in your root composer.json, composer update will either refuse or silently hold the plugin back at 1.3.0. Check composer why jeffersongoncalves/laravel-whatsapp-widget before assuming you got the translations. Also read the 2.0 changelog of the base package — a major bump there can move config keys or view names out from under any customizations you made against v1.

No migrations, no breaking changes in the plugin itself. 1.4.0 is translations plus CI/dependency housekeeping. Upgrading from 1.3.0 should be a no-op at runtime. If your tests break, suspect the base-package 2.0 bump, not the translations.

Phone number format bites everyone. wa.me links require digits only — no +, no spaces, no leading 00. A number entered as +44 7700 900123 produces a dead link with no error. Validate it in your own config or env var rather than trusting whoever filled in the config.

URL-encode the message. Newlines, &, #, and emoji in a pre-filled message will truncate or corrupt the link if not encoded. Test with a message containing a line break and an order number containing &.

Config caching. After publishing or editing the config, php artisan config:cache in production will hold stale values. This is the single most common "the widget still shows the old number" report.

Floating-widget collisions. This button sits at a fixed screen corner and will overlap Filament's own debug overlays, third-party chat widgets, or your cookie banner. Check the configured offset/position against whatever else floats in your UI, and verify on mobile viewports where the button can cover form submit buttons.

Translations cover chrome, not content. The new locales translate the package's own strings. Your tooltip override and pre-filled message are on you — a half-localized widget (Russian UI string, English message) looks worse than an untranslated one.

Assets and view overrides. If you published views or assets under 1.x, re-publish or diff after upgrading; view names can change on a base-package major. Prefer the plugin's view/config customization hooks over editing published files, so upgrades stay cheap.

Extension points. The plugin class and the published config are the intended surface. Subclassing the plugin is fine for adding your own fluent setters; copying the Blade view into your app is a last resort and creates upgrade debt.