Filament Whatsapp Conector Laravel Package

Getting Started

Minimal Steps

1. Installation:

   composer require wallacemartinss/filament-whatsapp-conector
   php artisan vendor:publish --tag="filament-evolution-config"
   php artisan vendor:publish --tag="filament-evolution-migrations"
   php artisan migrate
   

2. Register Plugin: Add to your PanelProvider:

   FilamentEvolutionPlugin::make()->whatsappInstanceResource()
   

3. Configure .env:

   EVOLUTION_URL=https://your-evolution-api.com
   EVOLUTION_API_KEY=your_api_key
   EVOLUTION_WEBHOOK_URL=https://your-app.com/api/webhooks/evolution
   EVOLUTION_WEBHOOK_SECRET=your_secret_key
   

4. Start Queue Worker:

   php artisan queue:work
   

5. First Use Case:

   • Navigate to WhatsApp > Instances in Filament.
   • Create a new instance, scan the QR code, and send a test message using the Send WhatsApp Message action.

Implementation Patterns

Core Workflows

1. Instance Management

• Create/Connect Instances: Use the Instances resource to manage WhatsApp connections. The QR code flow is automated via Livewire.

  // Customize instance creation in a Filament page
  FilamentEvolutionPlugin::make()
      ->whatsappInstanceResource()
      ->instanceSettings([
          'reject_call' => true,
          'always_online' => true,
      ]);
  

• Multi-Tenancy: Enable tenancy in config:

  'tenancy' => [
      'enabled' => true,
      'column' => 'tenant_id',
      'model' => App\Models\Tenant::class,
  ],
  

  Instances will auto-associate with the current tenant.

2. Sending Messages

• Filament Actions: Add to tables/pages/widgets:

  // Basic action
  SendWhatsappMessageAction::make()
      ->numberFrom('customer_phone') // Auto-fill from record
      ->instanceFrom('default_whatsapp_instance');
  
  // Pre-filled with defaults
  SendWhatsappMessageAction::make()
      ->number('551199999999')
      ->message('Your order #{{ $record->id }} is processing.')
      ->hideNumberInput();
  

• Programmatic Sending: Use the facade in controllers/services:

  Whatsapp::sendText($instanceId, '551199999999', 'Hello!');
  Whatsapp::sendImage($instanceId, '551199999999', 'path/to/image.jpg', 'Check this!');
  

• Service Integration: Extend your services with the trait:

  class NotificationService {
      use CanSendWhatsappMessage;
  
      public function sendOrderConfirmation(Order $order) {
          $this->sendWhatsappText(
              $order->customer->phone,
              "Your order #{$order->id} is confirmed!"
          );
      }
  }
  

3. Webhook Handling

• Route Webhooks: Add to routes/api.php:

  Route::post('/webhooks/evolution', [EvolutionWebhookController::class, 'handle']);
  

• Log Webhook Events: Enable in config:

  'storage' => [
      'webhooks' => true,
  ],
  

  View logs in WhatsApp > Webhook Logs.

• Process Events: Listen for events in services:

  event(new WhatsAppMessageReceived($messageData));
  

4. Interactive Messages (v2.4.0+)

• Buttons/List/CTA:

  Whatsapp::sendButtons(
      $instanceId,
      'Choose an option:',
      [
          ['type' => 'reply', 'title' => 'Yes', 'payload' => 'confirm'],
          ['type' => 'reply', 'title' => 'No', 'payload' => 'cancel'],
      ],
      'Order Confirmation',
      'Please confirm your order.'
  );
  

• Carousel:

  $cards = [
      [
          'title' => 'Product 1',
          'description' => 'Description 1',
          'image' => 'https://example.com/image1.jpg',
          'buttons' => [['type' => 'url', 'title' => 'Buy', 'url' => 'https://example.com']],
      ],
  ];
  Whatsapp::sendCarousel($instanceId, 'Products', $cards);
  

5. File Handling

• Upload Media: Files are stored on the default disk (configurable per action):

  SendWhatsappMessageAction::make()
      ->disk('s3'); // Override default disk
  

  Use storage_path('app/filament-whatsapp') for local paths.

• Cleanup: Schedule cleanup in routes/console.php:

  Schedule::command('evolution:cleanup')->daily();
  

Integration Tips

• Queue Jobs: Offload heavy operations (e.g., sending media) to queues:

  Whatsapp::dispatchSendImage($instanceId, $number, $path, $caption);
  

• Validation: Validate phone numbers before sending:

  use WallaceMartinss\FilamentEvolution\Rules\ValidWhatsAppNumber;
  
  $form->rules([
      'phone' => ['required', new ValidWhatsAppNumber],
  ]);
  

• Testing: Use the WhatsAppFake facade for tests:

  Whatsapp::fake();
  Whatsapp::assertSentText('551199999999', 'Hello!');
  

Gotchas and Tips

Pitfalls

1. QR Code Expiry:

   • QR codes expire after EVOLUTION_QRCODE_EXPIRES (default: 30 seconds). Refresh if it times out.
   • Fix: Increase the value in .env or handle the QRCodeExpired exception in your code.

2. Webhook Verification:

   • Always verify webhook signatures. The package includes middleware:

     Route::post('/webhooks/evolution', function () {
         return app(EvolutionWebhookMiddleware::class)->handle(...);
     });
     

   • Gotcha: Forgetting to set EVOLUTION_WEBHOOK_SECRET will cause webhooks to fail silently.

3. Media Storage:

   • Files uploaded via the action are stored in storage/app/filament-whatsapp by default.
   • Tip: Use a dedicated disk (e.g., S3) for production to avoid storage bloat:

     SendWhatsappMessageAction::make()->disk('s3');
     

4. Multi-Tenancy:

   • Instances are scoped to the current tenant. Ensure your tenant middleware is active.
   • Gotcha: Forgetting to enable tenancy in config will cause all instances to be global.

5. Rate Limiting:

   • Evolution API has rate limits. Handle TooManyRequestsException:

     try {
         Whatsapp::sendText($instanceId, $number, 'Message');
     } catch (TooManyRequestsException $e) {
         // Retry or notify admin
     }
     

6. Interactive Messages:

   • Requires Evolution API v2.4.0+. Check your API version before using buttons/list/CTA.
   • Tip: Use the supportsInteractiveMessages() method to verify:

     if (Whatsapp::supportsInteractiveMessages($instanceId)) {
         Whatsapp::sendButtons(...);
     }
     

Debugging

1. Webhook Failures:

   • Check logs in WhatsApp > Webhook Logs.
   • Enable debug mode in config:

     'debug' => true,
     

   • Verify the webhook URL is publicly accessible (use ngrok for local testing).

2. Message Not Delivered:

   • Check the sent_at and status fields in the database (whatsapp_messages table).
   • Tip: Use the WhatsAppFacade::getMessageStatus() method to fetch status updates.

3. QR Code Issues:

   • Ensure your phone has WhatsApp Web installed.
   • Debug: Log the QR code data:

     \Log::info('QR Code Data', ['data' => $instance->qr_code_data]);
     

4. Queue Stuck Jobs:

   • Monitor failed jobs in failed_jobs table.
   • Fix: Retry with:

     php artisan queue:retry all
     

Configuration Quirks

1. Default Instance:

   • Set EVOLUTION_DEFAULT_INSTANCE in .env to avoid selecting an instance manually.
   • Override: Pass an instance ID to actions/facade methods.

2. Cleanup Policy:

   • Old records are