kstmostofa/laravel-whatsapp

Laravel WhatsApp

Dual-backend WhatsApp integration for Laravel — Meta Cloud API (pure PHP) + whatsapp-web.js sidecar (full personal-account access), with a polished Livewire admin UI and a single WhatsApp:: facade across both.

📖 Full documentation: kstmostofa.github.io/laravel-whatsapp

What you get

Quick install

composer require kstmostofa/laravel-whatsapp
php artisan vendor:publish --tag=laravel-whatsapp-config
php artisan vendor:publish --tag=laravel-whatsapp-migrations
php artisan migrate

For the Cloud API — set in .env:

WHATSAPP_ACCESS_TOKEN=EAAG...permanent-token
WHATSAPP_PHONE_NUMBER_ID=123456789012345
WHATSAPP_BUSINESS_ACCOUNT_ID=987654321098765
WHATSAPP_APP_SECRET=your-meta-app-secret
WHATSAPP_VERIFY_TOKEN=any-string-you-make-up

For the Web sidecar — pair your phone:

composer require livewire/livewire livewire/flux           # for the UI
php artisan whatsapp:sidecar:install                       # one-time, ~600 MB Chrome download
php artisan whatsapp:sidecar:start                         # boots in background
php artisan whatsapp:web:listen --all &                    # SSE → Laravel events (run under Supervisor in prod)
# Open http://your-app.test/whatsapp/sessions and click "Start" → scan QR with your phone

Quick example

use Kstmostofa\LaravelWhatsApp\Facades\WhatsApp;
use Kstmostofa\LaravelWhatsApp\Jobs\SendMessage;

// One-line send — picks backend by recipient shape
WhatsApp::send('+9665XXXXXXXX', 'Hello from Laravel');           // → Cloud API
WhatsApp::send('966512345678@c.us', 'Hello via personal number'); // → Web sidecar

// Templated business message (Cloud API)
WhatsApp::messages()->sendTemplate('+9665XXXXXXXX', 'order_ready', 'en_US', [
    ['type' => 'body', 'parameters' => [['type' => 'text', 'text' => 'Munir']]],
]);

// Personal-number flow (Web sidecar — works for any chat your paired phone can see)
WhatsApp::web('main')->groups()->create('Project X', ['9665XXXXXXXX@c.us']);
WhatsApp::web('main')->messages()->sendImage('9665XXXXXXXX@c.us', ['url' => 'https://…/photo.jpg', 'caption' => 'Hi']);

// Many recipients — queued and rate limited
WhatsApp::bulk($numbers, 'Store opens at 10 today')->except($optedOut)->dispatch();

// Or queue a single send
SendMessage::dispatch('+9665XXXXXXXX', 'Queued hello');

// As a Laravel notification
$user->notify(new OrderShipped($order));   // via() => ['whatsapp'], toWhatsApp() => WhatsAppMessage

// In tests
WhatsApp::fake();
WhatsApp::assertSentTo('+9665XXXXXXXX', fn ($m) => str_contains($m->body, 'shipped'));

// Auto-replies — declared once in a service provider
WhatsApp::router()->hears('hi|hello', fn ($m) => $m->reply('Hi! How can I help?'));

// Inbound — or listen to the raw Laravel events
Event::listen(\Kstmostofa\LaravelWhatsApp\Events\Web\MessageReceived::class, function ($event) {
    Log::info('Got message', ['from' => $event->from(), 'body' => $event->body()]);
});

When to use which backend

Most apps use both — Cloud API for transactional/template sends at scale, Web sidecar for the features Cloud API doesn't expose.

UI install paths

The admin UI under /whatsapp works on whatever your app already uses:

Full setup details + dark mode + screenshots → docs site.

Artisan commands

Production checklist

• Set strong WHATSAPP_WEB_TOKEN (shared secret between PHP and sidecar)
• Set WHATSAPP_APP_SECRET (HMAC for Cloud webhook signatures)
• Wrap /whatsapp/* routes in your own auth middleware: config/laravel-whatsapp.php → ui.middleware
• Run whatsapp:web:listen --all under Supervisor / systemd
• Optional: isolate WA data on a separate DB connection (WHATSAPP_DB_CONNECTION=whatsapp)
• Optional: enable broadcasting (WHATSAPP_BROADCAST=true) + run Laravel Reverb for instant UI updates

Detailed deployment guide → docs/production.

Roadmap

• Cloud API: messages / templates / media / business profile / phone numbers / webhooks
• Web sidecar: full whatsapp-web.js surface (text, media, groups, contacts, status)
• Livewire + Flux admin UI with dark mode, 3 CSS install paths
• Eloquent persistence with per-package DB connection
• Health page + CLI command + cached snapshots
• Avatar + media proxy with server-side caching
• Bubble actions: edit, delete-for-me, delete-for-everyone, "you deleted this message" placeholder
• Bulk send job with rate limiting
• Laravel notification channel + WhatsApp::fake()
• Chat history import
• Larastan (level 6) + Pint in CI
• Native broadcasting integration with Echo channel listeners
• Template builder in Compose

Status

• 162 tests passing, 470 assertions (testbench + mocked Guzzle + Livewire smoke tests), plus 59 sidecar tests (npm test in sidecar/)
• Compatible with Laravel 12 / 13 — CI runs the suite on PHP 8.2, 8.3 and 8.4 with Laravel 12, and PHP 8.4 with Laravel 13, plus Pint and Larastan (level 6)
• PHP minimum: 8.2 on Laravel 12, 8.4 on Laravel 13 (Symfony 8 transitive)
• Laravel 11 support was dropped in 1.1.0: it is past end of life and has unpatched security advisories
• Verified end-to-end in Laravel 12 for the 1.0 feature set: QR pairing, inbound webhook → DB → UI bubble, edit, delete, sound, attachments, dark-mode toggle. Features added in 1.1 are covered by the automated tests above

License

MIT. See LICENSE.

Contributing

Issues + PRs welcome at github.com/kstmostofa/laravel-whatsapp. Before submitting, run:

composer check            # Pint style check, Larastan (level 6), and PHPUnit
composer format           # fix code style
cd sidecar && npm test    # sidecar unit tests (no npm install needed)

CI runs the same checks, plus the test suite across PHP 8.2–8.4 and Laravel 12 / 13.

If you change a Blade view, or StandaloneCssCoverageTest fails after a Flux update, rebuild the standalone stylesheet and commit dist/laravel-whatsapp.css:

LARAVEL_WHATSAPP_BUILD_APP=/path/to/laravel-app-with-flux ./dist-src/build.sh