Filament Twilio Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require tomatophp/filament-twilio
   php artisan config:cache
   

2. Configure .env:

   TWILIO_SID=your_account_sid
   TWILIO_TOKEN=your_auth_token
   TWILIO_SENDER_NUMBER=whatsapp:+14155238886  # Twilio WhatsApp sandbox number
   

3. Add Trait to Model: Attach InteractsWithTwilioWhatsapp to your User model (or any model needing WhatsApp notifications):

   use TomatoPHP\FilamentTwilio\Traits\InteractsWithTwilioWhatsapp;
   
   class User extends Authenticatable
   {
       use InteractsWithTwilioWhatsapp;
   }
   

4. First Notification: Send a test WhatsApp message via Filament’s notification facade:

   \Filament\Notifications\Notification::make()
       ->title('Test Notification')
       ->body('Hello from Twilio WhatsApp!')
       ->sendToTwilioWhatsapp(
           user: $user,
           mediaURL: null  // Optional: URL to media attachment
       );
   

Key Files to Review

• Config: config/filament-twilio.php (if extended later).
• Traits: Traits/InteractsWithTwilioWhatsapp.php (core logic).
• Service Provider: TomatoPHP\FilamentTwilio\FilamentTwilioServiceProvider (boot methods).

Implementation Patterns

Core Workflow

1. Notification Integration: Use Filament’s native Notification facade to send WhatsApp messages seamlessly alongside email/SMS notifications.

   Notification::make()
       ->title('Order Update')
       ->body('Your order #12345 is on its way!')
       ->sendToTwilioWhatsapp(user: $customer);
   

2. Dynamic Recipients: Leverage the sendToTwilioWhatsapp() method with model relationships:

   // Send to a user's associated contact (e.g., via `whatsapp_number` field)
   $user->sendTwilioWhatsappNotification(
       body: 'Custom message',
       mediaURL: asset('images/badge.png')
   );
   

3. Batch Sending: Combine with Laravel’s Notification::route() for bulk sends:

   $users->each(function ($user) {
       Notification::make()
           ->body('Promo code: SAVE20')
           ->sendToTwilioWhatsapp(user: $user);
   });
   

4. Filament Admin Panel: Trigger notifications from Filament actions/resources:

   // In a Filament Action
   public function sendWhatsApp(): void
   {
       Notification::make()
           ->body('Action triggered!')
           ->sendToTwilioWhatsapp(user: $this->record);
   }
   

Advanced Patterns

• Template Notifications: Use Filament’s notification templates with Twilio:

  Notification::make()
      ->template('custom.whatsapp') // Blade template
      ->sendToTwilioWhatsapp(user: $user);
  

• Media Attachments: Support for images/videos via mediaURL:

  Notification::make()
      ->body('Check this out!')
      ->sendToTwilioWhatsapp(
          user: $user,
          mediaURL: storage_path('app/brochure.pdf')
      );
  

• Fallback Logic: Chain with other notification channels for redundancy:

  Notification::make()
      ->body('Fallback: SMS if WhatsApp fails')
      ->toDatabase($user) // Fallback
      ->sendToTwilioWhatsapp(user: $user);
  

Gotchas and Tips

Common Pitfalls

1. Twilio Sandbox Restrictions:

   • Use whatsapp:+14155238886 (Twilio sandbox) for testing; cannot send to non-approved numbers.
   • For production, request Twilio to approve your number.

2. Media URL Validation:

   • Twilio rejects invalid URLs (e.g., local paths). Always use absolute, publicly accessible URLs:

     // ❌ Avoid
     mediaURL: 'storage/app/image.jpg'
     
     // ✅ Use
     mediaURL: Storage::url('image.jpg')
     

3. Rate Limits:

   • Twilio enforces WhatsApp messaging limits. Monitor failed sends in logs.

4. Model Field Requirements:

   • The trait assumes your model has a whatsapp_number field. Customize via:

     use TomatoPHP\FilamentTwilio\Traits\InteractsWithTwilioWhatsapp as BaseTrait;
     
     class User extends Authenticatable
     {
         use BaseTrait {
             getTwilioWhatsappNumber as private getCustomNumber;
         }
     
         public function getTwilioWhatsappNumber(): ?string
         {
             return $this->phone_number ?? null; // Custom field
         }
     }
     

Debugging Tips

• Enable Twilio Debugging: Add to .env:

  TWILIO_DEBUG=true
  

  Logs will appear in storage/logs/laravel.log.

• Check Twilio Console: Verify messages in Twilio Debugger for errors like:

  • 400 Bad Request: Invalid payload (e.g., missing body).
  • 403 Forbidden: Unapproved sender number.

• Filament Notification Logs: Enable Filament’s notification logging:

  // config/filament.php
  'notifications' => [
      'log' => true,
  ];
  

Extension Points

1. Customize Message Format: Override the trait’s getTwilioMessage() method:

   public function getTwilioMessage(string $body, ?string $mediaURL): array
   {
       return [
           'body' => "[Custom Prefix] $body",
           'mediaUrl' => $mediaURL,
           'from' => 'whatsapp:+1234567890', // Override sender
       ];
   }
   

2. Add New Channels: Extend the package to support SMS/email via the same facade:

   // Hypothetical extension
   Notification::make()
       ->body('Multi-channel')
       ->sendToTwilioSms(user: $user)
       ->sendToMail(user: $user);
   

3. Template Engine: Use Blade templates for dynamic content:

   Notification::make()
       ->template('notifications.whatsapp.order', ['order' => $order])
       ->sendToTwilioWhatsapp(user: $user);
   

4. Webhook Handling: Listen for Twilio delivery reports (requires Twilio Studio or custom webhook):

   Route::post('/twilio-webhook', function (Request $request) {
       // Handle delivery status updates
   });