PHPackages                             wallacemartinss/filament-whatsapp-conector - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. wallacemartinss/filament-whatsapp-conector

ActiveLibrary[API Development](/categories/api)

wallacemartinss/filament-whatsapp-conector
==========================================

Filament plugin for WhatsApp integration with Evolution API v2

2.0.0(4mo ago)641.4k—10%9[3 PRs](https://github.com/wallacemartinss/filament-whatsapp-conector/pulls)5MITPHPPHP ^8.2

Since Dec 8Pushed 4mo agoCompare

[ Source](https://github.com/wallacemartinss/filament-whatsapp-conector)[ Packagist](https://packagist.org/packages/wallacemartinss/filament-whatsapp-conector)[ Docs](https://github.com/wallacemartinss/filament-whatsapp-conector)[ RSS](/packages/wallacemartinss-filament-whatsapp-conector/feed)WikiDiscussions v2 Synced 1mo ago

READMEChangelogDependencies (13)Versions (6)Used By (5)

Filament Evolution - WhatsApp Connector
=======================================

[](#filament-evolution---whatsapp-connector)

[![Latest Version on Packagist](https://camo.githubusercontent.com/73e2b5ce47de9447a88dfbe4278e91ef78a28e3fa6b9876ad02711707c168710/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f77616c6c6163656d617274696e73732f66696c616d656e742d77686174736170702d636f6e6563746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/wallacemartinss/filament-whatsapp-conector)[![Total Downloads](https://camo.githubusercontent.com/84f05e5557fc0c0b9cfa9d2cf5981c238728dfeb17f216d775b7cf2d9ef18f7d/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f77616c6c6163656d617274696e73732f66696c616d656e742d77686174736170702d636f6e6563746f722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/wallacemartinss/filament-whatsapp-conector)

A Filament v5 plugin for WhatsApp integration using [Evolution API v2](https://doc.evolution-api.com/).

[![Filament Evolution - WhatsApp Connector](docs/images/principal.png)](docs/images/principal.png)

Features
--------

[](#features)

- 🔌 **Easy Integration** - Connect your WhatsApp with Evolution API v2
- 🏢 **Multi-Tenancy** - Full support for Filament's native multi-tenancy
- 📱 **QR Code Connection** - Real-time QR code display with countdown timer
- 📨 **Webhook Support** - Receive events from Evolution API (messages, connection updates, etc.)
- 💬 **Message Sending** - Send text, images, videos, audio, documents and more
- 🎯 **Filament Action** - Ready-to-use action for sending messages from anywhere
- 🔧 **Service Trait** - Easily integrate message sending into your own services
- 🔐 **Secure** - Credentials stored in config/env, never in database
- 🎨 **Filament v5 Native** - Beautiful UI with Filament components
- 🌍 **Translations** - Full i18n support (English and Portuguese included)
- ⚡ **Real-time** - Livewire-powered components with Alpine.js

Screenshots
-----------

[](#screenshots)

📸 Click to view screenshots[![Screenshot 1](docs/images/screenshot-01.png)](docs/images/screenshot-01.png)[![Screenshot 2](docs/images/screenshot-02.png)](docs/images/screenshot-02.png)[![Screenshot 3](docs/images/screenshot-03.png)](docs/images/screenshot-03.png)[![Screenshot 4](docs/images/screenshot-04.png)](docs/images/screenshot-04.png)[![Screenshot 5](docs/images/screenshot-05.png)](docs/images/screenshot-05.png)[![Screenshot 6](docs/images/screenshot-06.png)](docs/images/screenshot-06.png)[![Screenshot 7](docs/images/screenshot-07.png)](docs/images/screenshot-07.png)[![Screenshot 8](docs/images/screenshot-08.png)](docs/images/screenshot-08.png)Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 11.x or 12.x
- Filament v5
- Livewire v4
- Evolution API v2 instance

---

Installation
------------

[](#installation)

### Step 1: Install via Composer

[](#step-1-install-via-composer)

```
composer require wallacemartinss/filament-whatsapp-conector
```

### Step 2: Publish Configuration

[](#step-2-publish-configuration)

```
php artisan vendor:publish --tag="filament-evolution-config"
```

### Step 3: Run Migrations

[](#step-3-run-migrations)

```
php artisan vendor:publish --tag="filament-evolution-migrations"
php artisan migrate
```

### Step 4: Register the Plugin

[](#step-4-register-the-plugin)

Add the plugin to your Filament Panel Provider:

```
use WallaceMartinss\FilamentEvolution\FilamentEvolutionPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->plugins([
            FilamentEvolutionPlugin::make(),
        ]);
}
```

### Step 5: Configure Tailwind CSS

[](#step-5-configure-tailwind-css)

Add the plugin's views and source files to your Filament theme CSS file (e.g., `resources/css/filament/admin/theme.css`):

```
@import '../../../../vendor/filament/filament/resources/css/theme.css';

@source '../../../../app/Filament/**/*';
@source '../../../../resources/views/filament/**/*';

/* Add these lines for Filament Evolution */
@source '../../../../vendor/wallacemartinss/filament-whatsapp-conector/resources/views/**/*';
@source '../../../../vendor/wallacemartinss/filament-whatsapp-conector/src/**/*';
```

Then rebuild your assets:

```
npm run build
```

### Plugin Options

[](#plugin-options)

You can customize which resources are available in the panel:

```
FilamentEvolutionPlugin::make()
    ->viewMessageHistory()    // Enable message history resource
    ->viewWebhookLogs()       // Enable webhook logs resource
```

MethodDefaultDescription`whatsappInstanceResource(bool)``true`Show/hide the WhatsApp Instances resource`viewMessageHistory(bool)``false`Show/hide the Message History resource`viewWebhookLogs(bool)``false`Show/hide the Webhook Logs resource#### Example: Full Configuration

[](#example-full-configuration)

```
FilamentEvolutionPlugin::make()
    ->whatsappInstanceResource()  // Show instances (default: true)
    ->viewMessageHistory()        // Show message history
    ->viewWebhookLogs()           // Show webhook logs
```

---

Configuration
-------------

[](#configuration)

### Environment Variables (.env)

[](#environment-variables-env)

```
# Evolution API Connection (Required)
EVOLUTION_URL=https://your-evolution-api.com
EVOLUTION_API_KEY=your_api_key

# Webhook Configuration (Required for receiving events)
EVOLUTION_WEBHOOK_URL=https://your-app.com/api/webhooks/evolution
EVOLUTION_WEBHOOK_SECRET=your_secret_key
EVOLUTION_WEBHOOK_PATH=api/webhooks/evolution

# Storage Options (Optional - defaults to true)
EVOLUTION_STORE_WEBHOOKS=true
EVOLUTION_STORE_MESSAGES=true

# Instance Settings (Optional)
EVOLUTION_QRCODE_EXPIRES=30
EVOLUTION_DEFAULT_INSTANCE=your_instance_id
```

### Step 6: Start the Queue Worker

[](#step-6-start-the-queue-worker)

The plugin uses Laravel queues to process webhooks and send messages. Make sure you have a queue worker running:

```
php artisan queue:work
```

For production, use a process manager like Supervisor to keep the worker running. See the [Laravel Queue Documentation](https://laravel.com/docs/queues#supervisor-configuration) for more details.

### Config File

[](#config-file)

All other settings are in `config/filament-evolution.php`. Publish and customize:

```
php artisan vendor:publish --tag="filament-evolution-config"
```

Key configuration options:

```
// config/filament-evolution.php

return [
    // Queue settings
    'queue' => [
        'enabled' => true,
        'connection' => null,  // null = default connection
        'name' => 'default',   // queue name
    ],

    // Storage settings
    'storage' => [
        'webhooks' => true,    // save webhooks to database
        'messages' => true,    // save messages to database
    ],

    // Cleanup policy (automatic deletion of old records)
    'cleanup' => [
        'webhooks_days' => 30, // delete webhooks older than 30 days
        'messages_days' => 90, // delete messages older than 90 days
    ],

    // Instance defaults
    'instance' => [
        'reject_call' => false,
        'always_online' => false,
        // ...
    ],

    // Multi-tenancy
    'tenancy' => [
        'enabled' => false,
        'column' => 'team_id',
        'table' => 'teams',
        'model' => 'App\\Models\\Team',
    ],
];
```

---

Cleanup Command
---------------

[](#cleanup-command)

The plugin includes a cleanup command to remove old records:

```
# Run cleanup with config settings
php artisan evolution:cleanup

# Preview what would be deleted (dry run)
php artisan evolution:cleanup --dry-run

# Override config settings
php artisan evolution:cleanup --webhooks-days=7 --messages-days=30
```

### Scheduling Cleanup

[](#scheduling-cleanup)

Add to your `routes/console.php`:

```
use Illuminate\Support\Facades\Schedule;

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

---

Instance Management
-------------------

[](#instance-management)

### Creating an Instance

[](#creating-an-instance)

1. Navigate to **WhatsApp > Instances**
2. Click **New Instance**
3. Fill in the instance name and phone number
4. Configure settings (reject calls, always online, etc.)
5. Click **Save** - the QR Code modal will open automatically
6. Scan the QR Code with your WhatsApp

### Instance Settings

[](#instance-settings)

SettingDescription**Reject Calls**Automatically reject incoming calls**Message on Call**Message sent when rejecting calls**Ignore Groups**Don't process messages from groups**Always Online**Keep WhatsApp status as online**Read Messages**Automatically mark messages as read**Read Status**Automatically view status updates**Sync Full History**Sync all message history on connection---

Sending Messages
----------------

[](#sending-messages)

The plugin provides three ways to send WhatsApp messages:

1. **Filament Action** - For UI-based sending in tables, pages and widgets
2. **Whatsapp Facade** - For quick message sending anywhere
3. **CanSendWhatsappMessage Trait** - For integration into your services

### 1. Using the Filament Action

[](#1-using-the-filament-action)

The `SendWhatsappMessageAction` can be used in any Filament page, resource, or widget.

#### Basic Usage

[](#basic-usage)

```
use WallaceMartinss\FilamentEvolution\Actions\SendWhatsappMessageAction;

// In a table
public function table(Table $table): Table
{
    return $table
        ->actions([
            SendWhatsappMessageAction::make(),
        ]);
}

// In a page header
protected function getHeaderActions(): array
{
    return [
        SendWhatsappMessageAction::make(),
    ];
}
```

#### Pre-filling Values

[](#pre-filling-values)

```
SendWhatsappMessageAction::make()
    ->number('5511999999999')              // Default phone number
    ->instance($instanceId)                 // Default instance
    ->message('Hello World!')               // Default message
```

#### Using with Table Records

[](#using-with-table-records)

Get the phone number automatically from the record:

```
// Using attribute name
SendWhatsappMessageAction::make()
    ->numberFrom('phone'),

// Using dot notation for relationships
SendWhatsappMessageAction::make()
    ->numberFrom('contact.phone'),

// Using closure for custom logic
SendWhatsappMessageAction::make()
    ->numberFrom(fn ($record) => $record->celular ?? $record->telefone),

// Also set instance from record
SendWhatsappMessageAction::make()
    ->numberFrom('phone')
    ->instanceFrom('whatsapp_instance_id'),
```

#### Hiding Form Fields

[](#hiding-form-fields)

```
SendWhatsappMessageAction::make()
    ->hideInstanceSelect()     // Hide instance selector
    ->hideNumberInput()        // Hide phone number input
    ->textOnly()               // Only allow text messages (hide file upload)
```

#### Limiting Message Types

[](#limiting-message-types)

```
use WallaceMartinss\FilamentEvolution\Enums\MessageTypeEnum;

SendWhatsappMessageAction::make()
    ->allowedTypes([
        MessageTypeEnum::TEXT,
        MessageTypeEnum::IMAGE,
    ]);
```

#### Custom Storage Disk

[](#custom-storage-disk)

```
SendWhatsappMessageAction::make()
    ->disk('s3')   // Use S3 for file uploads
```

---

### 2. Using the Whatsapp Facade

[](#2-using-the-whatsapp-facade)

For programmatic message sending from anywhere in your application:

```
use WallaceMartinss\FilamentEvolution\Facades\Whatsapp;

// Send text
Whatsapp::sendText($instanceId, '5511999999999', 'Hello!');

// Send image with caption
Whatsapp::sendImage($instanceId, '5511999999999', 'path/to/image.jpg', 'Check this out!');

// Send video with caption
Whatsapp::sendVideo($instanceId, '5511999999999', 'path/to/video.mp4', 'Watch this!');

// Send audio
Whatsapp::sendAudio($instanceId, '5511999999999', 'path/to/audio.mp3');

// Send document
Whatsapp::sendDocument($instanceId, '5511999999999', 'path/to/file.pdf', 'report.pdf', 'Monthly Report');

// Send location
Whatsapp::sendLocation($instanceId, '5511999999999', -23.5505, -46.6333, 'My Office', 'São Paulo, SP');

// Send contact card
Whatsapp::sendContact($instanceId, '5511999999999', 'John Doe', '+5511888888888');

// Generic send method
Whatsapp::send($instanceId, '5511999999999', 'text', 'Hello World!');
Whatsapp::send($instanceId, '5511999999999', 'image', 'path/to/image.jpg', ['caption' => 'Nice!']);
```

---

### 3. Using the Trait in Your Services

[](#3-using-the-trait-in-your-services)

Add the `CanSendWhatsappMessage` trait to integrate message sending into your business logic:

```
use WallaceMartinss\FilamentEvolution\Concerns\CanSendWhatsappMessage;

class InvoiceService
{
    use CanSendWhatsappMessage;

    public function sendPaymentReminder(Invoice $invoice): void
    {
        $this->sendWhatsappText(
            $invoice->customer->phone,
            "Hello {$invoice->customer->name}, your invoice #{$invoice->number} is due on {$invoice->due_date->format('d/m/Y')}."
        );
    }

    public function sendInvoicePdf(Invoice $invoice): void
    {
        $this->sendWhatsappDocument(
            $invoice->customer->phone,
            $invoice->pdf_path,
            "invoice-{$invoice->number}.pdf",
            "Your invoice is ready!"
        );
    }

    public function sendPromoImage(Customer $customer, string $imagePath): void
    {
        $this->sendWhatsappImage(
            $customer->phone,
            $imagePath,
            "Special promotion just for you! 🎉"
        );
    }
}
```

#### Available Trait Methods

[](#available-trait-methods)

MethodDescription`sendWhatsappText($number, $message)`Send text message`sendWhatsappImage($number, $path, $caption)`Send image`sendWhatsappVideo($number, $path, $caption)`Send video`sendWhatsappAudio($number, $path)`Send audio`sendWhatsappDocument($number, $path, $fileName, $caption)`Send document`sendWhatsappLocation($number, $lat, $lng, $name, $address)`Send location`sendWhatsappContact($number, $contactName, $contactNumber)`Send contact card`sendWhatsappMessage($number, $type, $content, $options)`Generic send method`hasWhatsappInstance()`Check if an instance is available`getConnectedWhatsappInstances()`Get all connected instances#### Customizing the Instance Selection

[](#customizing-the-instance-selection)

Override `getWhatsappInstanceId()` to use a specific instance:

```
class TenantInvoiceService
{
    use CanSendWhatsappMessage;

    protected function getWhatsappInstanceId(): ?string
    {
        // Use tenant's specific WhatsApp instance
        return auth()->user()->tenant->whatsapp_instance_id;
    }
}
```

---

Storage Support
---------------

[](#storage-support)

The plugin supports both local and cloud storage (S3, etc.) for media files.

### Configuration

[](#configuration-1)

```
EVOLUTION_MEDIA_DISK=public
EVOLUTION_MEDIA_DIRECTORY=whatsapp-media
EVOLUTION_MEDIA_MAX_SIZE=16384
```

### Using Different Disks

[](#using-different-disks)

```
// Using the Facade with S3
Whatsapp::sendDocument($instanceId, $number, 'documents/report.pdf', 'report.pdf', null, 's3');

// Using the Action with custom disk
SendWhatsappMessageAction::make()->disk('s3');
```

---

Webhooks
--------

[](#webhooks)

The plugin includes a webhook endpoint to receive events from Evolution API.

### Available Events

[](#available-events)

EventDescription`APPLICATION_STARTUP`API started`QRCODE_UPDATED`New QR code generated`CONNECTION_UPDATE`Connection status changed`NEW_TOKEN`New authentication token`SEND_MESSAGE`Message sent`PRESENCE_UPDATE`Contact online/offline`MESSAGES_UPSERT`New message received### Webhook URL

[](#webhook-url)

Configure this URL in your Evolution API instance settings:

```
https://your-app.com/api/webhooks/evolution

```

> **Note:** The webhook route is `/api/webhooks/evolution` by default. Make sure your `EVOLUTION_WEBHOOK_URL` env variable matches this path.

---

Multi-Tenancy
-------------

[](#multi-tenancy)

The plugin supports Filament's native multi-tenancy. When enabled:

- All tables include the tenant foreign key
- Models automatically scope queries by tenant
- Records are auto-assigned to current tenant on creation

### Configuration

[](#configuration-2)

Edit the `config/filament-evolution.php` file:

```
'tenancy' => [
    'enabled' => true,
    'column' => 'team_id',
    'table' => 'teams',
    'model' => 'App\\Models\\Team',
    'column_type' => 'uuid', // 'uuid' or 'id'
],
```

---

Using the Evolution Client Directly
-----------------------------------

[](#using-the-evolution-client-directly)

For advanced use cases, you can use the Evolution client directly:

```
use WallaceMartinss\FilamentEvolution\Services\EvolutionClient;

$client = app(EvolutionClient::class);

// Create instance
$response = $client->createInstance('my-instance', '5511999999999', true, [
    'reject_call' => true,
    'always_online' => true,
]);

// Get connection state
$state = $client->getConnectionState('my-instance');

// Send text message
$client->sendText('my-instance', '5511999999999', 'Hello World!');

// Send image (path is base64 encoded by the service)
$client->sendImage('my-instance', '5511999999999', $base64Content, 'image.jpg', 'Check this!');
```

---

Testing
-------

[](#testing)

```
composer test
```

---

Changelog
---------

[](#changelog)

Please see [CHANGELOG](CHANGELOG.md) for more information on what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security Vulnerabilities
------------------------

[](#security-vulnerabilities)

Please review [our security policy](../../security/policy) on how to report security vulnerabilities.

Credits
-------

[](#credits)

- [Wallace Martins](https://github.com/wallacemartinss)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see [License File](LICENSE.md) for more information.

###  Health Score

48

—

FairBetter than 95% of packages

Maintenance78

Regular maintenance activity

Popularity35

Limited adoption so far

Community21

Small or concentrated contributor base

Maturity51

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 83.3% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~11 days

Total

5

Last Release

120d ago

Major Versions

v1.x-dev → 2.0.02026-01-19

### Community

Maintainers

![](https://www.gravatar.com/avatar/7c4ef517e623796f36a3912ade0c0db618939111f7be42f8de0d79bcc833ad57?d=identicon)[wallacemartinss](/maintainers/wallacemartinss)

---

Top Contributors

[![wallacemartinss](https://avatars.githubusercontent.com/u/56648941?v=4)](https://github.com/wallacemartinss "wallacemartinss (20 commits)")[![andrefelipe18](https://avatars.githubusercontent.com/u/96439642?v=4)](https://github.com/andrefelipe18 "andrefelipe18 (2 commits)")[![jeffersongoncalves](https://avatars.githubusercontent.com/u/411493?v=4)](https://github.com/jeffersongoncalves "jeffersongoncalves (2 commits)")

---

Tags

laravelwhatsappmulti-tenancyfilamentevolution-apibaileys

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/wallacemartinss-filament-whatsapp-conector/health.svg)

```
[![Health](https://phpackages.com/badges/wallacemartinss-filament-whatsapp-conector/health.svg)](https://phpackages.com/packages/wallacemartinss-filament-whatsapp-conector)
```

###  Alternatives

[bezhansalleh/filament-shield

Filament support for `spatie/laravel-permission`.

2.8k2.9M88](/packages/bezhansalleh-filament-shield)[relaticle/custom-fields

User Defined Custom Fields for Laravel Filament

15828.6k](/packages/relaticle-custom-fields)[croustibat/filament-jobs-monitor

Background Jobs monitoring like Horizon for all drivers for FilamentPHP

254255.2k6](/packages/croustibat-filament-jobs-monitor)[rupadana/filament-api-service

A simple api service for supporting filamentphp

204103.8k7](/packages/rupadana-filament-api-service)[tapp/filament-webhook-client

Add a Filament resource and a policy for Spatie Webhook client

1120.2k](/packages/tapp-filament-webhook-client)[guava/filament-modal-relation-managers

Allows you to embed relation managers inside filament modals.

7565.0k4](/packages/guava-filament-modal-relation-managers)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)