gowa-php/filament

Filament v3 / v4 / v5 plugin for GOWA WhatsApp integration

v1.0.0 2026-08-31 13:04 UTC

Requires

• php: ^8.2
• filament/filament: ^3.0|^4.0|^5.0
• gowa-php/laravel: ^1.0
• gowa-php/sdk: ^1.0
• illuminate/contracts: ^10.0|^11.0|^12.0
• illuminate/support: ^10.0|^11.0|^12.0

Requires (Dev)

• orchestra/testbench: ^8.0|^9.0|^10.0
• pestphp/pest: ^3.0
• pestphp/pest-plugin-livewire: ^3.0

MIT

• Aguinaldo Tupy

Published on Packagist.org on 2026-08-31 13:13 UTC

README

gowa-php/filament

Filament v5 / v4 / v3 plugin for integrating GOWA WhatsApp instances into Laravel Filament applications

🇧🇷 Para ler a documentação em Português, acesse README.pt.md.

⚡ Acknowledgments & Ecosystem Dependencies

This package is Phase 3 of the GOWA PHP ecosystem and interacts with the open-source Go backend ecosystem:

• whatsmeow — The underlying Go library created by Tulir Asokan that reverse-engineers the WhatsApp Web Multi-Device WebSocket protocol and Signal encryption.
• go-whatsapp-web-multidevice (GOWA) — The lightweight REST API wrapper created by Aldino Kemal exposing whatsmeow over HTTP and Webhooks.
• gowa-php/sdk — Pure PHP SDK for GOWA REST API and Webhook parsing.
• gowa-php/laravel — Laravel integration providing Facades, Notification Channels, Webhook routes, and Eloquent models.

📦 Prerequisites & Requirements

• Running GOWA Server: An active instance of go-whatsapp-web-multidevice (GOWA). GOWA_BASE_URL is required in your .env.
• PHP: >= 8.2
• Laravel: ^10.0 | ^11.0 | ^12.0
• Filament: ^5.0 (Tested & Verified) | ^3.0 | ^4.0 (Architectural Compatibility)
• GOWA Packages: gowa-php/sdk ^1.2, gowa-php/laravel ^1.2

🔧 Installation

Install the package via Composer:

composer require gowa-php/filament

Publish the configuration file (optional):

php artisan vendor:publish --tag="gowa-filament-config"

⚙️ Environment Configuration (.env)

Add the GOWA server connection credentials to your .env file:

# GOWA WhatsApp Server Connection
GOWA_BASE_URL=https://gowa.yourcompany.com
GOWA_USERNAME=admin
GOWA_PASSWORD=secret
GOWA_TIMEOUT=15

# Webhook Configuration (Optional)
GOWA_WEBHOOK_SECRET=your_hmac_secret
GOWA_WEBHOOK_PATH=webhooks/gowa

⚡ Quick Start

Add GowaPlugin to your Filament Panel Provider (e.g., AdminPanelProvider.php):

use Gowa\Filament\GowaPlugin;

public function panel(Panel $panel): Panel
{
    return $panel
        ->default()
        ->id('admin')
        ->path('admin')
        ->plugins([
            GowaPlugin::make(),
        ]);
}

✨ Key Features

• 📱 GOWA Instance Resource (GowaInstanceResource): View, create, edit, and manage connected WhatsApp instances with slide-over modals and native Filament Infolists.
• 🔗 Webhook Synchronization & Secret Generator: Synchronize webhook URLs and HMAC secrets directly with the GOWA Go server without disconnecting. Includes a 32-character random secret generator action.
• 📷 Real-Time QR Code Modal: Scan QR codes directly in Filament with automatic polling (wire:poll.3s).
• 🔢 8-Digit Pairing Code Modal: Link WhatsApp using a phone number with copy-to-clipboard pairing code.
• 🧪 Messaging Test Sandbox (GowaMessagingPage): Interactive playground supporting all 11 GOWA message formats:
  • 💬 Text: Plain text messages with reply targeting.
  • 🖼️ Image: Image upload with native Filament Image Editor (crop, rotate, flip).
  • 🎥 Video: Video file uploads (.mp4, .avi, .mov).
  • 📄 Document / File: Upload PDFs, CSVs, DOCX, XLSX, ZIP archives up to 50MB.
  • 🎙️ Audio / Voice Note: Send audio files or simulate voice notes (PTT).
  • 🏷️ Sticker: Send WebP/PNG stickers.
  • 👤 Contact Card: Share WhatsApp contact cards.
  • 📍 Location: Share GPS coordinates with location names and addresses.
  • 🔗 Link Preview: Send links with automated open-graph previews.
  • 📊 Poll: Interactive multi-option voting polls.
  • 📡 Presence Status: Update typing (composing) or recording (recording) status.
• ✉️ Specialized Resource Actions:
  • SendGowaMessageAction: Quick text messages with dynamic templates.
  • SendGowaDocumentAction: Send PDFs, invoices, contracts, or spreadsheets via file path or URL.
  • SendGowaMediaAction: Send images, videos, or audio with custom captions.
  • UpdateWebhookAction: Instantly synchronize webhook URL and HMAC secret settings with GOWA backend.
• 📊 Real-time Status Widget (GowaDeviceStatusWidget): Dashboard card displaying Connected, Connecting, and Offline instances.
• 🌐 Multilingual Support: Built-in English (en) and Portuguese (pt_BR) translations.

💡 Specialized Actions Usage Examples

1. Send Quick Text Message (SendGowaMessageAction)

Add a WhatsApp text action to any Filament Resource table:

use Gowa\Filament\Actions\SendGowaMessageAction;

public static function table(Table $table): Table
{
    return $table
        ->columns([ ... ])
        ->actions([
            SendGowaMessageAction::make()
                ->numberFrom('phone_number') // Resolves recipient phone from record
                ->message(fn ($record) => "Hello {$record->name}, your order #{$record->id} has been shipped!"),
        ]);
}

2. Send PDF Document or Invoice (SendGowaDocumentAction)

Easily dispatch invoices, contracts, or report PDFs to customers:

use Gowa\Filament\Actions\SendGowaDocumentAction;

SendGowaDocumentAction::make('sendInvoice')
    ->label('Send Invoice PDF')
    ->numberFrom('customer.phone')
    ->documentUrl(fn ($record) => $record->pdf_download_url)
    ->filename(fn ($record) => "invoice-{$record->code}.pdf");

3. Send Media / Photos / Videos (SendGowaMediaAction)

Send image receipts, product photos, or video attachments with custom captions:

use Gowa\Filament\Actions\SendGowaMediaAction;
use Gowa\Sdk\Dto\MediaType;

SendGowaMediaAction::make('sendReceipt')
    ->label('Send Payment Receipt')
    ->type(MediaType::Image)
    ->numberFrom('client_phone')
    ->mediaFrom('receipt_path')
    ->caption('Here is your payment confirmation receipt.');

🧪 Testing

Run Pest PHP tests:

composer test

⚠️ Disclaimer & Terms of Use

This software is an open-source library created for educational, research, and testing laboratory purposes.

• Third-Party Terms of Service: Users of this library are solely responsible for complying with WhatsApp's Terms of Service, Meta's Platform Policies, and the terms of any third-party services utilized.
• Automated Messaging & Policy Compliance: Automated or unauthorized messaging may violate platform terms. Users must ensure strict compliance with applicable privacy laws (e.g., GDPR, LGPD), user consent requirements, and platform guidelines.
• No Warranty & Liability: This software is provided "as is", without warranty of any kind, express or implied. The authors and contributors assume no liability for any account bans, data loss, service interruptions, or misuse of this library.

📄 License

The MIT License (MIT). Please see LICENSE for more information.