README

Plug-and-play WhatsApp AI sales agent for Laravel, powered by OpenAI.
Install once, customise per client via a single config file.

Requirements

• PHP 8.2+
• Laravel 11 or 12
• An OpenWA (WWebJS) session running and accessible via HTTP
• An OpenAI API key

Installation

composer require nexus-smart-solutions/whatsapp-ai-agent

Laravel auto-discovers the service provider. No manual registration needed.

Setup (3 steps)

1. Publish the config

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

This creates config/whatsapp-ai-agent.php in your project.
This is the only file you edit per client.

2. Add environment variables to .env

OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4o-mini
OPENAI_TEMPERATURE=0.7

OPENWA_BASE_URL=http://localhost:3000
OPENWA_API_KEY=your-openwa-api-key
OPENWA_SESSION=your-session-uuid

# Optional overrides
AI_WEBHOOK_URI=webhook/whatsapp
AI_HISTORY_LIMIT=10
AI_HUMAN_ACTIVE_MINUTES=30

3. Run migrations

Migrations load automatically from the package.
Just run:

php artisan migrate

Or publish them first if you want to inspect or modify them:

php artisan vendor:publish --tag=whatsapp-ai-agent-migrations
php artisan migrate

Customising the AI per client

Open config/whatsapp-ai-agent.php and edit the system_prompt key:

'system_prompt' => 'You are a sales agent for Acme Corp ...',

You can also load it from an external file to keep the config clean:

'system_prompt' => file_get_contents(base_path('prompts/agent.txt')),

Webhook URL

The package registers the route automatically:

POST /webhook/whatsapp

Point your OpenWA session webhook to:

https://your-client-domain.com/webhook/whatsapp

To change the URI, update AI_WEBHOOK_URI in .env or edit config/whatsapp-ai-agent.php.

To disable auto-routing (if you want to register the route manually):

WHATSAPP_AI_REGISTER_ROUTES=false

Then in your routes/api.php:

Route::post('/my-custom-path', [\Nexus\WhatsAppAiAgent\Http\Controllers\WhatsAppWebhookController::class, 'handle']);

Human Agent Takeover

The AI automatically goes silent when a human agent is active.
Update these columns on the ai_conversations table from your agent dashboard:

Using the services directly

All three services are bound in the container and can be injected:

use Nexus\WhatsAppAiAgent\Services\ConversationService;

class MyController extends Controller
{
    public function __construct(
        private readonly ConversationService $agent
    ) {}
}

Tables created