Laravel Notification Whatsapp Laravel Package

Getting Started

• Install the package with Composer and pin the new release for Laravel 12 projects:

  composer require netflie/laravel-notification-whatsapp:^1.4
  

• Publish/configure the package config if your install uses it, then set WhatsApp API credentials in .env. Run php artisan config:clear after credential changes.
• Look first at:
  • The package README for the exact config keys and notification channel name.
  • config/whatsapp.php or the package’s published config file.
  • Component.php and Component/Document.php if you send media.
  • An existing notification class that already uses WhatsAppChannel.
• First use case: send a simple WhatsApp notification to a notifiable model, then add a document attachment:

  public function via(object $notifiable): array
  {
      return [\Netflie\WhatsApp\WhatsAppChannel::class];
  }
  
  public function toWhatsapp(object $notifiable)
  {
      return \Netflie\WhatsApp\WhatsAppMessage::create()
          ->document('https://example.com/invoices/123.pdf', 'invoice-123.pdf');
  }
  

  The second document() argument is new in 1.4.0 and is optional. Existing calls with only the document URL should continue to work.

Implementation Patterns

• Use Laravel notifications as the primary integration point. Add the WhatsApp channel to via() and implement the package’s toWhatsapp() method on the notification.
• Keep recipient routing on the notifiable model where possible, e.g. a routeNotificationForWhatsapp() method or a dedicated phone column. Avoid hard-coding phone numbers inside notifications.
• Use the message builder for text, media, and document messages. For documents, prefer the new explicit filename when the recipient should see a business-friendly name:

  return WhatsAppMessage::create()
      ->document($invoiceUrl, "invoice-{$invoice->number}.pdf");
  

• Centralize document URL generation. A signed URL or public disk URL is usually safer than exposing internal storage paths.
• Queue WhatsApp notifications with ShouldQueue for non-critical sends. This keeps request latency down and lets Laravel retry failed API calls.
• Test notifications with Notification::fake() and assert the channel/notification was sent. For payload-level tests, inspect the message object’s toArray() output; 1.4.0 includes the document filename there.
• For a Laravel 12 upgrade, bump the package to ^1.4, update your app’s Illuminate constraints, and run the notification test suite. The release updates illuminate/notifications and illuminate/support for Laravel 12.
• If you maintain custom notification channels or wrappers, keep message construction isolated so the optional filename can be passed through without changing callers.

Gotchas and Tips

• Laravel 12 support arrives in 1.4.0. If you are on Laravel 12, do not stay on 1.3.x; Composer dependency constraints may block installation or resolution.
• The new filename parameter is optional and backwards-compatible. Existing document($url) calls should still work, but explicitly setting a filename avoids provider-side filename inference and gives recipients a cleaner download name.
• The filename is now part of the document component payload via toArray(). If you snapshot or log message payloads in tests, update expectations only where you assert exact arrays.
• Media/document URLs generally must be publicly reachable by WhatsApp. Local paths, private storage URLs without signatures, and short-lived URLs can fail after the notification is queued but before it is sent.
• Queueing plus retries can cause duplicate WhatsApp messages. Make sends idempotent where possible, or avoid automatic retries for notifications that must not duplicate.
• Clear Laravel’s config cache after changing WhatsApp credentials or config values; queued workers can otherwise keep stale config.
• Debug by logging the message toArray() before sending and by checking the WhatsApp API/provider response. For document failures, verify URL accessibility, MIME type, file size limits, and filename extension.
• phpstan/phpstan 2.1 support is development/static-analysis related, not a runtime feature. It should not affect production behavior.
• No breaking changes are indicated in 1.4.0. The meaningful upgrade items are Laravel 12 compatibility and the optional document filename.