PHPackages kstmostofa/laravel-whatsapp - 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. kstmostofa/laravel-whatsapp ActiveLibrary[API Development](/categories/api) kstmostofa/laravel-whatsapp =========================== Dual-backend Laravel package for WhatsApp: Meta Cloud API + bundled whatsapp-web.js sidecar. Ships a Livewire/Flux admin UI, queued jobs, webhooks with HMAC, Eloquent models, broadcasting, and CLI lifecycle commands. v1.0.0(2w ago)25132MITPHPPHP ^8.2CI passing Since May 22Pushed 2w agoCompare [ Source](https://github.com/kstmostofa/laravel-whatsapp)[ Packagist](https://packagist.org/packages/kstmostofa/laravel-whatsapp)[ Docs](https://kstmostofa.github.io/laravel-whatsapp/)[ RSS](/packages/kstmostofa-laravel-whatsapp/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (10)Versions (2)Used By (0) Laravel WhatsApp ================ [](#laravel-whatsapp) [![Latest Version](https://camo.githubusercontent.com/7002b990201d8aabbfc06029242b109d8596fe6e334dd0b3398b6ba072d6bd45/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6b73746d6f73746f66612f6c61726176656c2d77686174736170702e737667)](https://packagist.org/packages/kstmostofa/laravel-whatsapp)[![PHP Version](https://camo.githubusercontent.com/a7064c0130ee210198b067fa8f167db439257bed599ab9bdb8ce10424de28c5b/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6b73746d6f73746f66612f6c61726176656c2d77686174736170702e737667)](https://packagist.org/packages/kstmostofa/laravel-whatsapp)[![License](https://camo.githubusercontent.com/f827ecb2b3dbd6ba0fb82e132ba390b2cbca670c2099e86c462ef1ba9bcfd8af/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6b73746d6f73746f66612f6c61726176656c2d77686174736170702e737667)](LICENSE) > 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](https://kstmostofa.github.io/laravel-whatsapp) --- What you get ------------ [](#what-you-get) LayerWhat it does**Cloud API client**Pure PHP. Templates, media, business profile, phone-number management, webhooks with HMAC verification.**Web sidecar** (~300 LOC Node)`whatsapp-web.js` wrapped in a thin HTTP service. Personal-number QR pairing, groups, status, free-form messages anytime, contact lookup.**Unified facade**`WhatsApp::messages()->sendTemplate(...)` for Cloud, `WhatsApp::web('main')->messages()->sendText(...)` for sidecar. `WhatsApp::send($to, $body)` auto-picks.**Livewire + Flux UI**Drop-in admin at `/whatsapp` — Dashboard, Sessions+QR, Compose, Conversations (chat-bubble UI with media, edit/delete, search, sound, ack ticks), Groups, Contacts, Webhooks log, Status. Works with Tailwind, Bootstrap, or no CSS framework at all.**Eloquent models**Opt-in `WaSession` / `WaMessage` / `WaContact` with separate-DB support via `WHATSAPP_DB_CONNECTION`.**Background bridge**`whatsapp:web:listen` daemon turns sidecar SSE events into Laravel events.**Health monitoring**`WhatsApp::status` page + `php artisan whatsapp:health [--json]` for CI/monitoring.--- Quick install ------------- [](#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 main & # 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 ------------- [](#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']); // Or queue it SendMessage::dispatch('+9665XXXXXXXX', 'Queued hello'); // Inbound — listen via 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 ------------------------- [](#when-to-use-which-backend) FeatureCloud APIWeb sidecarPersonal-number QR pairing❌✅Send to / receive from groups❌✅Status / Stories❌✅Free-form messages anytime❌ (templates outside 24h)✅Approved business templates✅❌Official, no ban risk✅❌ (browser automation — ToS gray area)Scalable to millions✅⚠️ session-boundNo extra runtime on host✅❌ (Node + Chromium)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 ---------------- [](#ui-install-paths) The admin UI under `/whatsapp` works on whatever your app already uses: Your app uses…Set in `.env`What you getTailwind v4 + Vite`WHATSAPP_UI_CSS_MODE=vite` (default)Smallest tree-shaken bundle. Add 3 `@source` lines to your `app.css`.Anything else (Tailwind v3 / Bootstrap / plain CSS / nothing)`WHATSAPP_UI_CSS_MODE=standalone`Pre-compiled CSS shipped with the package, served from `/whatsapp/_assets/laravel-whatsapp.css` (~32 KB gz). No npm/Tailwind needed. Loads only on `/whatsapp/*` pages — your main app stays untouched.No UI at allskip `composer require livewire/flux`Headless. Full access to `WhatsApp::` facade, Events, Jobs, webhook receiver, all CLI commands.Full setup details + dark mode + screenshots → [docs site](https://kstmostofa.github.io/laravel-whatsapp/ui). Artisan commands ---------------- [](#artisan-commands) CommandPurpose`whatsapp:sidecar:install`Clone whatsapp-web.js, `npm ci`, download Chromium`whatsapp:sidecar:start` / `:stop` / `:status`Lifecycle of the Node process`whatsapp:web:listen [session]`Long-running: sidecar SSE → Laravel events`whatsapp:health [--json]` \[`--exit-code`\]Health probe — pipe into cron / monitoringProduction checklist -------------------- [](#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` under Supervisor / systemd, one process per session - 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](https://kstmostofa.github.io/laravel-whatsapp/production). Roadmap ------- [](#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 - Native broadcasting integration with `Echo` channel listeners - Template builder UI (currently API-only) Status ------ [](#status) - **46 tests passing**, 133 assertions (testbench + mocked Guzzle + Livewire smoke tests) - **Compatible with Laravel 11 / 12 / 13** — tests run green against L13.11 + PHPUnit 12 on PHP 8.5 - PHP minimum: **8.2** on Laravel 11/12, **8.4** on Laravel 13 (Symfony 8 transitive) - **Verified end-to-end in Laravel 12**: QR pairing, inbound webhook → DB → UI bubble, edit, delete, sound, attachments, dark-mode toggle License ------- [](#license) MIT. See [LICENSE](LICENSE). Contributing ------------ [](#contributing) Issues + PRs welcome at [github.com/kstmostofa/laravel-whatsapp](https://github.com/kstmostofa/laravel-whatsapp). Please run `vendor/bin/phpunit` locally before submitting. ### Health Score 44 — FairBetter than 90% of packages Maintenance96 Actively maintained with recent releases Popularity18 Limited adoption so far Community7 Small or concentrated contributor base Maturity46 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 Unknown Total 1 Last Release 18d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/f1f46e3f91d5f4540359404b883e5bb5330c6bd13746bdce5cfacecee7858e56?d=identicon)[kstmostofa](/maintainers/kstmostofa) --- Top Contributors [![kstmostofa](https://avatars.githubusercontent.com/u/48328034?v=4)](https://github.com/kstmostofa "kstmostofa (4 commits)") --- Tags laravelfluxlivewiremessagingwebhookswhatsappmetachatbotwhatsapp-businesswhatsapp-cloud-apiwhatsapp-webwhatsapp-web-js ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/kstmostofa-laravel-whatsapp/health.svg) ``` [![Health](https://phpackages.com/badges/kstmostofa-laravel-whatsapp/health.svg)](https://phpackages.com/packages/kstmostofa-laravel-whatsapp) ``` ### Alternatives [spatie/laravel-health Monitor the health of a Laravel application 87311.3M149](/packages/spatie-laravel-health)[spatie/laravel-export Create a static site bundle from a Laravel app 670139.5k6](/packages/spatie-laravel-export)[larastan/larastan Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel 6.4k51.0M7.4k](/packages/larastan-larastan)[laravel/mcp Rapidly build MCP servers for your Laravel applications. 76318.2M110](/packages/laravel-mcp)[psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9732.3M121](/packages/roots-acorn) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)