PHPackages jigar-dhulla/laravel-whatsapp-ai-agent - 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. [Utility & Helpers](/categories/utility) 4. / 5. jigar-dhulla/laravel-whatsapp-ai-agent ActiveLibrary[Utility & Helpers](/categories/utility) jigar-dhulla/laravel-whatsapp-ai-agent ====================================== A Laravel package for building WhatsApp AI agents on top of wacli. v0.2.3(2w ago)2553[4 issues](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent/issues)MITPHPPHP ^8.3CI passing Since May 4Pushed 2w agoCompare [ Source](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent)[ Packagist](https://packagist.org/packages/jigar-dhulla/laravel-whatsapp-ai-agent)[ RSS](/packages/jigar-dhulla-laravel-whatsapp-ai-agent/feed)WikiDiscussions 0.2 Synced 1w ago READMEChangelog (6)Dependencies (5)Versions (12)Used By (0) Laravel WhatsApp AI Agent ========================= [](#laravel-whatsapp-ai-agent) [![Tests](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent/actions/workflows/tests.yml/badge.svg)](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent/actions/workflows/tests.yml)[![Lint](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent/actions/workflows/lint.yml/badge.svg)](https://github.com/jigar-dhulla/laravel-whatsapp-ai-agent/actions/workflows/lint.yml)[![Latest Version on Packagist](https://camo.githubusercontent.com/797e3030c0e3fa5771ac226c584c5a4ee208e1a0f59672325498b2929381ec16/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6a696761722d6468756c6c612f6c61726176656c2d77686174736170702d61692d6167656e742e737667)](https://packagist.org/packages/jigar-dhulla/laravel-whatsapp-ai-agent)[![License](https://camo.githubusercontent.com/ba8991083ad88022ab3456b227de220de72e9b2632b1efeeb78935731b70c6ce/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6a696761722d6468756c6c612f6c61726176656c2d77686174736170702d61692d6167656e742e737667)](LICENSE) An extension to the [Laravel AI SDK](https://laravel.com/docs/ai-sdk) that adds WhatsApp as an agent interface. It polls a [wacli](https://github.com/steipete/wacli) SQLite database for new messages, routes them through your configured agents (any class that implements `Laravel\Ai\Contracts\Agent`), and sends replies back via the wacli binary. Intro & Demo ---------------- [](#intro--demo) Watch the intro and demo on YouTube: Requirements ------------ [](#requirements) - PHP 8.3+ - Laravel 13.0+ - `laravel/ai` ^0.6 - [`wacli`](https://github.com/steipete/wacli) **0.8.1+** installed and authenticated on the host Installation ------------ [](#installation) ``` composer require jigar-dhulla/laravel-whatsapp-ai-agent ``` The package registers itself automatically via Laravel's package auto-discovery. Setup ----- [](#setup) Run the setup command to detect your wacli binary and write paths to `.env`: ``` php artisan wa:setup ``` This will: 1. Locate your wacli binary 2. Run `wacli doctor` to detect your store directory 3. Prompt for the wacli SQLite database path 4. Write `WA_WACLI_BINARY`, `WA_WACLI_STORE`, and `WA_WACLI_DATABASE` to `.env` Then publish the config to customize your agents: ``` php artisan vendor:publish --tag=whatsapp-agent-config ``` This publishes `config/whatsapp-agent.php`, which includes a default `WhatsAppAgent` ready to use. Edit the config to add your own agents or customize scopes and triggers. Configuration ------------- [](#configuration) ### `config/whatsapp-agent.php` [](#configwhatsapp-agentphp) ``` return [ 'wacli' => [ 'binary' => env('WA_WACLI_BINARY', 'wacli'), 'database' => env('WA_WACLI_DATABASE'), 'store' => env('WA_WACLI_STORE'), ], /* | One entry per agent. The agent key must be a class that implements | Laravel\Ai\Contracts\Agent (use the Promptable trait for the full SDK | feature set). Provider and model are optional runtime overrides; if null, | the agent class resolves them via its own #[Provider]/#[Model] attributes | or config/ai.php defaults. | | - triggers: [] matches every message in this agent's scope | - chats/groups: at least one entry total — empty scope = inactive agent */ 'agents' => [ [ 'agent' => \JigarDhulla\LaravelWhatsApp\Agents\WhatsAppAgent::class, 'triggers' => [], 'chats' => [], 'groups' => [], ], ], 'polling' => [ 'interval_seconds' => (int) env('WA_POLLING_INTERVAL', 1), ], ]; ``` **AI provider configuration (API keys, default models) belongs in `config/ai.php`**, managed by `laravel/ai` — not in this package. ### Environment Variables [](#environment-variables) VariableDefaultDescription`WA_WACLI_BINARY``wacli`Path to the wacli binary (0.6.0+ required)`WA_WACLI_DATABASE`—Path to the wacli SQLite database (set by `wa:setup`)`WA_WACLI_STORE`—Path to the wacli store directory (set by `wa:setup`)`WA_POLLING_INTERVAL``1`Seconds between database polls`WA_HISTORY_LIMIT``100`Max past messages included in agent context### Creating Custom Agents [](#creating-custom-agents) Generate a new agent with `make:agent`: ``` php artisan make:agent CustomAgent ``` This creates `app/Ai/Agents/CustomAgent.php`. Then add it to your published `config/whatsapp-agent.php`: ``` 'agents' => [ [ 'agent' => \App\Ai\Agents\CustomAgent::class, 'triggers' => ['@custom'], 'chats' => ['111@s.whatsapp.net'], 'groups' => [], ], ], ``` You can keep the default `WhatsAppAgent` in the config alongside your custom agents, or remove it entirely. #### Conversation memory [](#conversation-memory) Add the `RemembersWhatsAppConversations` trait to your agent to give it access to the full message history from the wacli SQLite database. The trait implements the Laravel AI SDK's conversation interface, so previous messages in the chat are automatically injected as context on every prompt: ``` use JigarDhulla\LaravelWhatsApp\Traits\RemembersWhatsAppConversations; use Laravel\Ai\Contracts\Agent; use Laravel\Ai\Contracts\Conversational; use Laravel\Ai\Promptable; class CustomAgent implements Agent, Conversational { use Promptable; use RemembersWhatsAppConversations; } ``` The number of historical messages included is controlled by `WA_HISTORY_LIMIT` (default `100`). Override `maxConversationMessages()` in your agent class to set a per-agent limit. Both direct messages and group chats are supported. In groups, the agent automatically distinguishes participants so it can address each person individually. ### Multiple Agents [](#multiple-agents) One message can match multiple agents simultaneously. Each match dispatches an independent queued job, so agents process in parallel: ``` // config/whatsapp-agent.php 'agents' => [ [ 'agent' => \App\Ai\Agents\SupportAgent::class, 'triggers' => ['@support'], 'chats' => ['111@s.whatsapp.net'], 'groups' => ['group1@g.us'], ], [ 'agent' => \App\Ai\Agents\SalesAgent::class, 'triggers' => ['@sales'], 'chats' => ['111@s.whatsapp.net'], 'groups' => [], ], [ 'agent' => \App\Ai\Agents\BroadcastAgent::class, 'triggers' => [], // empty = matches all messages in scope 'chats' => [], 'groups' => ['announcements@g.us'], ], ], ``` **Routing rules:** - A message matches an agent when its chat/group JID is in the agent's `chats` or `groups` list **and** the body contains at least one trigger phrase (case-insensitive). - An empty `triggers` array matches every message in scope. - An agent with empty `chats` **and** empty `groups` is inactive and never fires. Usage ----- [](#usage) ### Start the wacli sync daemon [](#start-the-wacli-sync-daemon) ``` wacli sync --follow --refresh-contacts --refresh-groups ``` You may use a 3rd party tool to make sure this keeps running. ### Start the listener [](#start-the-listener) ``` php artisan wa:listen ``` Runs an infinite polling loop. Each iteration syncs new wacli messages, routes them via `AgentRouter`, and dispatches one `ProcessWhatsAppMessage` job per matched agent. ``` php artisan wa:listen --once # single iteration, then exit php artisan wa:listen --max-iterations=10 php artisan wa:listen -vv # show startup config summary php artisan wa:listen -vvv # show each message scanned ``` ### Check agent status [](#check-agent-status) ``` php artisan wa:status ``` Shows wacli auth/connection state and a summary of every configured agent — class name, provider/model, triggers, and scope. ### Queue worker [](#queue-worker) Each matched message dispatches a `ProcessWhatsAppMessage` job. Run a queue worker alongside the listener: ``` php artisan queue:work ``` How It Works ------------ [](#how-it-works) ``` wacli sync → SQLite DB → WhatsAppMessageReader → AgentRouter ↓ (one job per match) ProcessWhatsAppMessage (queued) ↓ $agent->prompt($body) ↓ wacli send text ``` 1. `wa:listen` runs as daemon. 2. `WhatsAppMessageReader` fetches rows newer than the last processed rowid, filtered to the union of all agents' JIDs. 3. `AgentRouter::match($chatJid, $body)` returns every agent config entry whose scope contains the chat and whose triggers match the message. 4. One `ProcessWhatsAppMessage` job is dispatched per matched entry. 5. The job resolves the agent class from the container, calls `$agent->prompt($body)`, and sends the reply via `wacli send text`. Testing ------- [](#testing) ``` composer install vendor/bin/phpunit vendor/bin/pint ``` License ------- [](#license) MIT — see [LICENSE](LICENSE). ### Health Score 44 — FairBetter than 90% of packages Maintenance93 Actively maintained with recent releases Popularity21 Limited adoption so far Community6 Small or concentrated contributor base Maturity45 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 Every ~2 days Total 8 Last Release 19d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/dd37364fd509a890b4ba371bc90b7cf68aff2a730e202e81503596260e2df486?d=identicon)[jigarakatidus](/maintainers/jigarakatidus) --- Top Contributors [![jigar-dhulla](https://avatars.githubusercontent.com/u/3132291?v=4)](https://github.com/jigar-dhulla "jigar-dhulla (8 commits)") ### Code Quality TestsPHPUnit Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/jigar-dhulla-laravel-whatsapp-ai-agent/health.svg) ``` [![Health](https://phpackages.com/badges/jigar-dhulla-laravel-whatsapp-ai-agent/health.svg)](https://phpackages.com/packages/jigar-dhulla-laravel-whatsapp-ai-agent) ``` ### Alternatives [unopim/unopim UnoPim Laravel PIM 10.1k2.2k](/packages/unopim-unopim)[markwalet/nova-modal-response A Laravel Nova asset for Modal responses on an action. 17818.7k](/packages/markwalet-nova-modal-response)[tomshaw/electricgrid A feature-rich Livewire package designed for projects that require dynamic, interactive data tables. 119.2k](/packages/tomshaw-electricgrid) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)