Filament Multifactor Whatsapp Laravel Package

Getting Started

Assessment: Treat this as a focused Filament 5 MFA provider, not a full WhatsApp notification platform. It is useful when you already use Filament’s multi-factor authentication flow and want WhatsApp OTP as an additional factor. With 17 stars, zero dependents, and a very recent release, pin the version and review the source before using it on high-assurance production panels.

Minimal steps

1. Install into a Laravel app running Filament 5:

   composer require jeffersongoncalves/filament-multifactor-whatsapp
   

2. Publish the package config and any migrations, then run migrations:

   php artisan vendor:publish --tag=filament-multifactor-whatsapp-config
   php artisan vendor:publish --tag=filament-multifactor-whatsapp-migrations
   php artisan migrate
   

   Confirm the actual publish tags in the package README/service provider; tag names can vary between Filament plugins.

3. Add a WhatsApp-capable phone field to your authenticatable model if it does not already have one. Prefer E.164 format, e.g. +994501234567:

   Schema::table('users', function (Blueprint $table) {
       $table->string('whatsapp_phone')->nullable()->after('email');
   });
   

   Make it fillable or manageable through your Filament user resource. Check the published config for the expected attribute name; do not assume it is phone.

4. Configure the optional Evolution API connector in .env if you want the package to send messages through your Evolution API instance:

   EVOLUTION_API_URL=https://evolution.example.com
   EVOLUTION_API_KEY=your-api-key
   EVOLUTION_API_INSTANCE=your-instance
   

   Map these to the exact config keys published by the package. If you do not use Evolution API, check whether the package supports a custom sender/connector before relying on it.

5. Register the package’s WhatsApp MFA provider in your Filament panel provider alongside any existing factors:

   use JeffersonGoncalves\FilamentMultifactorWhatsapp\Multifactor\WhatsAppAuthentication;
   
   public function panel(Panel $panel): Panel
   {
       return $panel
           ->multiFactorAuthentication([
               WhatsAppAuthentication::make()
                   ->recoverable(),
           ]);
   }
   

   The exact provider class/namespace should be taken from the README; the important pattern is that it plugs into Filament’s native multiFactorAuthentication() array.

6. Log in as a test user with a valid WhatsApp phone number, enroll the factor, and verify that the OTP challenge appears after password authentication.

First use case: Add WhatsApp OTP as a second factor for an internal Filament admin panel whose users are already known and whose phone numbers are maintained by an administrator. Start with one panel and a small pilot group. Do not begin by making WhatsApp the only second factor for every user.

Where to look first

• The package README for the exact provider class, config keys, and publish tags.
• The published config file for phone attribute, OTP lifetime, connector, and Evolution API settings.
• Filament’s own MFA documentation for the panel-level multiFactorAuthentication() API, recovery codes, and user contracts.
• The package source for the OTP generation, rate limiting, and Evolution API request path, especially if you plan to use it in production.

Implementation Patterns

Panel-level enrollment

Keep the integration in the panel provider, not scattered across controllers. Filament’s MFA system owns the challenge flow; the package supplies the WhatsApp factor. A typical pattern:

->multiFactorAuthentication([
    WhatsAppAuthentication::make()
        ->recoverable(),
])

If you already use app-based or email MFA, add WhatsApp as an additional option rather than replacing the existing factor. This lets you fall back to another factor if WhatsApp delivery fails.

Self-service enrollment and phone verification

The main day-to-day workflow is:

1. User signs in with email/password.
2. Filament prompts for MFA enrollment if required.
3. User confirms their WhatsApp number.
4. Package sends an OTP through Evolution API.
5. User enters the code.
6. Filament stores the MFA state for that user.

Expose the phone number in your Filament profile page or user resource, but restrict who can change it. A user who can silently change their WhatsApp number can potentially redirect their own second factor. For sensitive panels, require an administrator or a second verification step before changing the MFA phone number.

Evolution API connector pattern

Use the package’s Evolution API integration as a transport adapter, not as your business logic. Keep these concerns separate:

• Your app: owns users, phone numbers, MFA enrollment state, audit logs.
• Package: generates/validates OTP and calls the connector.
• Evolution API: owns WhatsApp session/instance state and message delivery.

In application code, avoid calling Evolution API directly for MFA. If you need custom message templates, delivery auditing, or retries, check whether the package exposes a connector contract or notification extension point. If not, wrap the package behavior in your own service and log the outcome around it.

Multi-panel and multi-guard setups

If you have separate Filament panels for admins, staff, and customers, decide deliberately which panels enable WhatsApp MFA. Register the provider only on panels where the user model has a reliable WhatsApp number.

A common pattern is:

• Admin panel: WhatsApp MFA required, plus recovery codes.
• Staff panel: WhatsApp MFA optional during rollout.
• Customer panel: no MFA, or a separate lower-friction flow.

Avoid sharing one MFA configuration across panels with different user populations unless you have verified that every authenticatable model supports the same phone attribute and enrollment state.

Testing and local development

Do not send real WhatsApp messages in every test. Check whether the package’s connector can be faked or swapped. If it cannot, isolate the MFA flow behind a local test double or use a dedicated Evolution API test instance.

At minimum, test:

• Enrollment with a valid phone number.
• Invalid and expired OTP.
• OTP reuse attempt.
• Missing or malformed phone number.
• Evolution API timeout/failure.
• Recovery code path.
• User without a phone number attempting to enroll.
• Disabling and re-enabling the factor.

Rollout pattern

For an existing Filament app, roll out in stages:

1. Add the phone column and backfill known numbers.
2. Enable WhatsApp MFA on a staging panel.
3. Pilot with internal users.
4. Add recovery codes and support documentation.
5. Enable for the wider group.
6. Monitor delivery failures and support requests.

Keep a documented fallback: recovery codes, another MFA factor, or an administrator-assisted reset. WhatsApp delivery depends on an external service and a phone number the user may lose.

Gotchas and Tips

This package is young. With 17 stars and no dependents, it has little public production history. Pin the exact version in composer.json, review the OTP and connector code, and test upgrades against your Filament version. Do not assume long-term API stability.

Filament 5 only. Confirm your Filament major version before installing. Filament’s MFA APIs changed across versions, and mixing this package with Filament 3/4 patterns will waste time.

Phone normalization is the most likely integration bug. WhatsApp requires a country code. Store numbers in E.164 format and validate before enrollment. Decide how to handle numbers without a country code, leading zeros, spaces, and local formats. A number that works in your UI may fail in Evolution API if it is not normalized.

Check the config’s phone attribute. The package may expect a specific column name such as phone, whatsapp_phone, or a configurable attribute. Set it explicitly in the published config and make the model attribute fillable/cast correctly.

Evolution API is an external dependency. Delivery can fail because the instance is disconnected, the API key is wrong, the session expired, the number is invalid, or the service is rate-limited. Do not treat “OTP sent” as “OTP delivered.” Log connector failures and show a useful error to the user.

Do not log OTP codes. It is tempting during debugging, but OTPs are credentials. Log correlation IDs, user IDs, and connector status instead. If you must inspect a code in local development, use a dedicated local test mode rather than production logs.

Rate-limit and expire codes. Confirm the package enforces OTP expiry, attempt limits, and resend throttling. If it does not, add throttling at the Filament action or application layer. Also decide whether an OTP can be reused; it should not be.

Use recovery codes. WhatsApp is not a guaranteed channel. A lost phone, changed number, or disconnected Evolution instance can lock users out. Enable Filament’s recovery-code support and document the recovery process before enforcing MFA.

Cache and queue configuration matter. If OTP state is stored in cache, use a shared cache store across app nodes. If sending is queued, confirm the queue worker is running and that failures are visible. A synchronous Evolution API call can also slow down the login flow; check timeouts.

Translations are present but incomplete by default. Release 1.1.0 adds az, fa, hi, pt, and uz locales. Publish or override translations if your UI needs different wording, and verify the package’s translation keys are loaded in your panel.

Upgrade and dependency risk. The package tracks Filament 5 and has frequent dependency bumps. Run composer update --dry-run and test MFA enrollment after Filament or package upgrades. Keep an eye on the changelog and release notes.

Extension points to look for. Before writing custom code, check whether the package exposes configuration for:

• OTP length and lifetime.
• Message template.
• Custom connector or sender.
• Phone attribute.
• Rate limiting.
• Notification class.

If those extension points do not exist, prefer wrapping the package at the panel/service level rather than forking it immediately. If you do fork, keep the fork small and document why.

Overall recommendation: Use this package for internal Filament admin panels where WhatsApp is a convenient additional factor and you can tolerate some operational risk. For customer-facing or high-assurance authentication, wait for more adoption, add a second MFA factor, and budget time for connector monitoring, recovery flows, and phone-number hygiene.