README

Talk to your Laravel AI SDK agents over WhatsApp, using wacli to connect to your account.

▶️ Watch the intro & demo

Requirements

• PHP 8.3+ and Laravel 13+
• laravel/ai with an AI provider configured in config/ai.php
• wacli 0.8.1+, installed and logged in to WhatsApp

Getting Started

1. Install the package

composer require jigar-dhulla/laravel-whatsapp-ai-agent

2. Point it at wacli. This finds your wacli binary and database and writes the paths to .env:

php artisan wa:setup

3. Publish the config

php artisan vendor:publish --tag=whatsapp-agent-config

4. Choose which chats the agent answers. List your chat and group IDs (JIDs):

php artisan wa:chats     # direct messages
php artisan wa:groups    # groups

Add them to the agent in config/whatsapp-agent.php. An agent with no chats and no groups stays inactive.

'agents' => [
    [
        'agent'    => \JigarDhulla\LaravelWhatsApp\Agents\WhatsAppAgent::class,
        'triggers' => [],                         // [] = reply to every message
        'chats'    => ['15551234567@s.whatsapp.net'],
        'groups'   => [],
    ],
],

5. Run it. Start these three processes and keep them running:

wacli sync --follow --refresh-contacts --refresh-groups   # sync WhatsApp → local DB
php artisan wa:listen                                      # route new messages to agents
php artisan queue:work                                     # run agents and send replies

Now send a message from one of the chats you configured. Your agent will reply.

Stuck? Run php artisan wa:status to check that wacli is authenticated and connected, and to see how your agents are configured.

Configuration

Agent options

Each entry in agents supports:

A message goes to every agent whose chats/groups include that chat and whose triggers appear in the message. Replying to one of the agent's own messages also triggers it, even without a trigger phrase.

The provider, model and API keys come from config/ai.php or from the agent class. This package doesn't set them.

Environment variables

Examples

A custom agent

php artisan make:agent SupportAgent

// app/Ai/Agents/SupportAgent.php
namespace App\Ai\Agents;

use JigarDhulla\LaravelWhatsApp\Traits\RemembersWhatsAppConversations;
use Laravel\Ai\Contracts\Agent;
use Laravel\Ai\Contracts\Conversational;
use Laravel\Ai\Promptable;

class SupportAgent implements Agent, Conversational
{
    use Promptable, RemembersWhatsAppConversations; // the trait gives the agent the chat history

    public function instructions(): string
    {
        return 'You are a friendly support agent for Acme Inc. Keep replies short.';
    }
}

// config/whatsapp-agent.php
'agents' => [
    [
        'agent'    => \App\Ai\Agents\SupportAgent::class,
        'triggers' => ['@support'],
        'chats'    => [],
        'groups'   => ['120363000000000000@g.us'],
        'mention_sender' => true,
    ],
],

Several agents in one group

Each agent answers only to its own trigger:

'agents' => [
    ['agent' => \App\Ai\Agents\SupportAgent::class, 'triggers' => ['@support'], 'chats' => [], 'groups' => ['team@g.us']],
    ['agent' => \App\Ai\Agents\SalesAgent::class,   'triggers' => ['@sales'],   'chats' => [], 'groups' => ['team@g.us']],
],

Answer when your number is @-mentioned

Run php artisan wa:status to find your linked JID. Then use your number as the trigger:

'triggers' => ['@15551234567'],

Commands

Contributing

See CONTRIBUTING.md. Run the tests with composer test and fix code style with composer format.

License

MIT. See LICENSE.