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 panel() method in your Filament Panel Provider:

   FilamentEvolutionPlugin::make()
       ->whatsappInstanceResource()
       ->viewMessageHistory()
       ->viewWebhookLogs()
   

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
   

First Use Case

Send a WhatsApp message from a Filament resource:

use WallaceMartinss\FilamentEvolution\Actions\SendWhatsappMessageAction;

public function table(Table $table): Table
{
    return $table
        ->actions([
            SendWhatsappMessageAction::make()
                ->numberFrom('phone') // Auto-fill from record
                ->instanceFrom('whatsapp_instance_id'),
        ]);
}

Implementation Patterns

Core Workflows

1. Instance Management

• Create & Connect:

  • Navigate to WhatsApp > Instances → New Instance
  • Scan QR code to connect (auto-opens modal with countdown timer)
  • Configure settings (reject calls, always online, etc.)

• Multi-Instance Handling:

  // Get all connected instances
  $instances = Whatsapp::getConnectedInstances();
  
  // Use specific instance
  Whatsapp::sendText($instanceId, '5511999999999', 'Hello!');
  

2. Message Sending Patterns

• From Filament UI:

  // In a page header
  protected function getHeaderActions(): array
  {
      return [
          SendWhatsappMessageAction::make()
              ->number('5511999999999')
              ->instance(1)
              ->message('Default message'),
      ];
  }
  

• From Business Logic:

  class NotificationService
  {
      use CanSendWhatsappMessage;
  
      public function sendOrderConfirmation(Order $order)
      {
          $this->sendWhatsappText(
              $order->customer_phone,
              "Your order #{$order->id} is confirmed!"
          );
  
          if ($order->has_invoice) {
              $this->sendWhatsappDocument(
                  $order->customer_phone,
                  storage_path("app/invoices/{$order->invoice}.pdf"),
                  "invoice_{$order->invoice}.pdf",
                  "Your invoice is attached."
              );
          }
      }
  }
  

3. Webhook Integration

• Handle Incoming Events:

  // routes/web.php
  Route::post('/api/webhooks/evolution', [EvolutionWebhookController::class, 'handle']);
  
  // Controller
  public function handle(Request $request)
  {
      return Whatsapp::handleWebhook($request);
  }
  

• Process Webhook Events:

  // Listen for message events
  event(new WhatsappMessageReceived($messageData));
  

4. Interactive Messages (v2.4.0+)

• Reply Buttons:

  Whatsapp::sendWhatsappButtons(
      '5511999999999',
      'Choose an option:',
      [
          ['type' => 'reply', 'title' => 'Yes', 'payload' => 'confirm'],
          ['type' => 'reply', 'title' => 'No', 'payload' => 'cancel'],
      ],
      'Survey',
      'Please select an option'
  );
  

• PIX Payments:

  Whatsapp::sendWhatsappPix(
      '5511999999999',
      'Pay your invoice:',
      '00020126500014BR.GOV.BCB.PIX0114+55119999999995204000053039865802BR5913Your Company Name6009SAO PAULO62070503***63041234',
      'Invoice Payment',
      'Payment due: R$100.00'
  );
  

5. Multi-Tenancy

• Configure in .env:

  EVOLUTION_TENANCY_ENABLED=true
  EVOLUTION_TENANCY_COLUMN=team_id
  

• Instance Isolation:

  // Automatically scopes to current tenant
  $tenantInstances = Whatsapp::getConnectedInstances();
  

Integration Tips

1. Queue Management

• Batch Processing:

  // Dispatch jobs for async sending
  SendWhatsappMessage::dispatch($instanceId, $number, 'text', 'Hello!');
  

• Monitor Jobs: Use Laravel Horizon or php artisan queue:work --once for debugging.

2. File Handling

• Custom Storage:

  SendWhatsappMessageAction::make()
      ->disk('s3') // Use S3 for uploads
      ->allowedTypes([MessageTypeEnum::IMAGE, MessageTypeEnum::DOCUMENT]);
  

• Local Paths:

  Whatsapp::sendImage($instanceId, '5511999999999', storage_path('app/images/product.jpg'), 'Check this out!');
  

3. Error Handling

• Retry Failed Jobs:

  // In FailedJob.php
  public function handle()
  {
      $job = $this->job;
      if ($job instanceof SendWhatsappMessage) {
          $job->release(5); // Retry after 5 seconds
      }
  }
  

• Logging:

  try {
      Whatsapp::sendText($instanceId, $number, $message);
  } catch (\Exception $e) {
      Log::error("WhatsApp send failed: {$e->getMessage()}");
  }
  

4. Testing

• Mock Webhooks:

  // tests/Feature/WhatsAppTest.php
  public function test_webhook_received()
  {
      $response = $this->postJson('/api/webhooks/evolution', [
          'event' => 'message',
          'data' => [...],
      ]);
  
      $response->assertOk();
      $this->assertDatabaseHas('whatsapp_webhook_logs', [...]);
  }
  

• Stub Facade:

  Whatsapp::shouldReceive('sendText')
      ->once()
      ->with($instanceId, $number, $message);
  

5. Performance

• Bulk Sending:

  foreach ($customers as $customer) {
      SendWhatsappMessage::dispatch($instanceId, $customer->phone, 'text', $message);
  }
  

• Queue Throttling:

  // config/filament-evolution.php
  'queue' => [
      'enabled' => true,
      'connection' => 'redis',
      'name' => 'whatsapp',
      'delay' => 1000, // 1 second delay between jobs
  ],
  

Gotchas and Tips

Pitfalls

1. QR Code Expiry:

   • QR codes expire after EVOLUTION_QRCODE_EXPIRES (default: 30 seconds).
   • Fix: Refresh the page or regenerate the QR code if it times out.

2. Webhook Verification:

   • Always verify webhook signatures in production:

   public function handle(Request $request)
   {
       if (!Whatsapp::verifyWebhook($request)) {
           abort(403, 'Invalid signature');
       }
       return Whatsapp::handleWebhook($request);
   }
   

3. File Size Limits:

   • Evolution API has file size limits (e.g., 10MB for documents).
   • Tip: Compress large files or use cloud storage (S3).

4. Multi-Tenancy Conflicts:

   • Ensure EVOLUTION_TENANCY_COLUMN matches your tenant model’s key.
   • Debug: Check tenancy config in filament-evolution.php.

5. Queue Stuck Jobs:

   • Monitor failed_jobs table for stuck WhatsApp jobs.
   • Fix: Restart queue worker or manually retry:

   php artisan queue:retry all
   

6. Interactive Messages (v2.4.0+):

   • Requires Evolution API v2.4.0+. Check your instance’s API version.
   • Error: `Unsupported