Getting Started

Minimal Setup

Installation:

composer require kstmostofa/laravel-whatsapp
php artisan vendor:publish --provider="KstMostofa\WhatsApp\WhatsAppServiceProvider"

Publish the config and migrations:

php artisan migrate

Configure .env: Add Meta Cloud API or whatsapp-web.js credentials:

WHATSAPP_PROVIDER=meta_cloud  # or whatsapp_web
WHATSAPP_META_API_KEY=your_api_key
WHATSAPP_WEB_JS_URL=http://localhost:3000  # Sidecar endpoint

First Use Case: Send a test message via the facade:

use KstMostofa\WhatsApp\Facades\WhatsApp;

WhatsApp::send('+1234567890', 'Hello from Laravel!');

Where to Look First

Facade API: src/Facades/WhatsApp.php Focus on methods like send(), getChats(), and getMedia().
Config: config/whatsapp.php Adjust provider, credentials, and webhook settings.
Livewire Admin: resources/views/livewire/whatsapp/admin.blade.php Customize the UI if needed (optional).

Implementation Patterns

Core Workflows

1. Sending Messages

Transactional Messages (OTPs, alerts):

WhatsApp::send('+1234567890', 'Your OTP is: ' . $otp);

Templates (Meta Cloud API compliant):

WhatsApp::sendTemplate('+1234567890', 'order_update', [
    'order_id' => '#12345',
    'amount' => '$99.99'
]);

2. Handling Incoming Messages

Webhook Setup (for whatsapp-web.js): Add a route in routes/web.php:

Route::post('/whatsapp/webhook', [WhatsAppWebhookController::class, 'handle']);

Implement the controller to process events:

public function handle(Request $request) {
    $event = WhatsApp::parseWebhook($request);
    // Handle message, status updates, etc.
}

3. Admin Management

Livewire Integration: Add the admin panel to a blade view:
```
@livewire('whatsapp.admin')
```
Customize the Livewire component in app/Http/Livewire/WhatsApp/Admin.php.

4. Queue-Based Processing

Offload message sending to a queue (e.g., for bulk operations):

WhatsApp::queue()->send('+1234567890', 'Delayed message');

Configure the queue in config/whatsapp.php:

'queue' => [
    'enabled' => true,
    'connection' => 'redis',
],

Integration Tips

Laravel Notifications: Extend the WhatsAppChannel for seamless integration:

use KstMostofa\WhatsApp\Notifications\WhatsAppChannel;

class WhatsAppMessage extends Notification {
    public function via($notifiable) {
        return [WhatsAppChannel::class];
    }
}

Service Providers: Bind custom providers (e.g., for extended functionality):

WhatsApp::extend('custom', function () {
    return new CustomWhatsAppProvider();
});

Middleware: Add auth/validation middleware to WhatsApp routes:

Route::middleware(['auth:sanctum'])->group(function () {
    Route::post('/whatsapp/send', [WhatsAppController::class, 'send']);
});

Testing: Use the WhatsAppFake for unit tests:

use KstMostofa\WhatsApp\Testing\WhatsAppFake;

public function test_send_message() {
    WhatsAppFake::fake();
    WhatsApp::send('+1234567890', 'Test');
    WhatsAppFake::assertSent('Test');
}

Gotchas and Tips

Pitfalls

Dual-Backend Complexity:
- Issue: whatsapp-web.js sidecar may crash or lose session if not properly monitored.
- Fix: Use a process manager (e.g., PM2) or Kubernetes for the sidecar. Store QR codes in a database for recovery:
```
// Recover a lost session
WhatsApp::recoverSession('+1234567890');
```
Meta Cloud API Quotas:
- Issue: Unexpected 429 Too Many Requests errors if quotas are exceeded.
- Fix: Monitor usage via Meta’s dashboard and implement exponential backoff in your code:
```
try {
    WhatsApp::send($phone, $message);
} catch (\KstMostofa\WhatsApp\Exceptions\RateLimitException $e) {
    sleep($e->retryAfter);
    retry();
}
```
Livewire Admin UI:
- Issue: UI may not align with your app’s design system.
- Fix: Override Livewire views in resources/views/livewire/whatsapp/ or extract components into reusable widgets.
Webhook Delays:
- Issue: whatsapp-web.js webhooks may be delayed or dropped.
- Fix: Implement a retry queue for failed webhook deliveries and log payloads for debugging.
Phone Number Formatting:
- Issue: Invalid phone numbers (e.g., missing +) cause API failures.
- Fix: Validate and format numbers before sending:
```
use KstMostofa\WhatsApp\Support\PhoneNumber;

$phone = PhoneNumber::format('1234567890'); // Returns '+1234567890'
```

Debugging Tips

Enable Logging: Add to config/whatsapp.php:
```
'logging' => [
    'enabled' => true,
    'channel' => 'single',
],
```
Check logs in storage/logs/whatsapp.log.

Sidecar Debugging: For whatsapp-web.js, inspect logs via:

docker logs <container_name>  # If using Docker

Or attach to the process:

node --inspect whatsapp-web.js

API Response Inspection: Enable debug mode in the facade:
```
WhatsApp::debug(true);
```
Responses will be logged with request/response details.

Extension Points

Custom Providers: Extend the WhatsAppProvider interface for new backends:

class CustomProvider implements \KstMostofa\WhatsApp\Contracts\WhatsAppProvider {
    public function send($phone, $message) { ... }
    public function getChats() { ... }
}

'providers' => [
    'custom' => \App\Providers\CustomWhatsAppProvider::class,
],

Message Templates: Add custom templates for Meta Cloud API:

WhatsApp::addTemplate('order_confirmation', [
    'components' => [
        'header' => ['type' => 'text', 'text' => 'Order #{{1}}'],
        // ...
    ],
]);

Webhook Handlers: Extend the WhatsAppWebhookHandler for custom logic:

WhatsApp::extendWebhookHandler(function ($event) {
    if ($event->type === 'message') {
        // Custom logic for incoming messages
    }
});

Queue Jobs: Publish and extend the queue job:
```
php artisan vendor:publish --tag=whatsapp-queue-jobs
```
Customize app/Jobs/SendWhatsAppMessage.php.

Configuration Quirks

Provider Switching: Dynamically switch providers at runtime:

WhatsApp::setProvider('whatsapp_web'); // Fallback to web.js

Media Handling: For large media, use streaming:

WhatsApp::sendMedia($phone, 'image.jpg', [
    'caption' => 'Check this out!',
    'stream' => true, // Stream file instead of uploading
]);

Rate Limiting: Configure custom rate limits in `config/whatsapp

Laravel Whatsapp Laravel Package