README

A comprehensive WhatsApp integration package for Laravel with support for Meta WhatsApp Business API and WhatsAppJS Client, featuring real-time chat functionality, OTP verification, notifications, and attachment handling.

Features

🔄 Dual Provider Support: Switch between Meta WhatsApp Business API and WhatsAppJS Client
🚀 Real-time Chat: Powered by Laravel Broadcasting and Pusher
⚛️ Vue.js Support: Modern Vue 3 components with Inertia.js
🔧 Blade Templates: Traditional Blade templates as alternative
👥 Multi-user Support: Admin and user roles with different interfaces
📱 WhatsApp Verification: Built-in OTP phone number verification system
🔔 Notifications: Laravel notification system integration
📎 Attachments: Full support for images, documents, audio, and video
🎨 Modern UI: Beautiful, responsive chat interface
📊 Admin Dashboard: Separate admin interface with conversation management
🔗 External Number Assignment: Assign external numbers to registered users
📝 Message History: Complete conversation history and search
🛡️ Security: CSRF protection, HMAC verification, and authentication middleware
🔄 Re-engagement: Automatic template message handling for Meta API
📦 Message Queue: Retry failed messages automatically

⚠️ Important: WhatsApp Client Gateway

For WhatsAppJS Client mode: This package includes the Node.js gateway service in the whatsapp-client-gateway directory. You must set it up and run it before testing Client mode. See the Gateway Setup section below.

For Meta Business API mode: No additional services required - just configure your API credentials.

Installation

1. Install via Composer

composer require devsfort/laravel-whatsapp-chat

2. Run the Installation Command

php artisan whatsapp-chat:install

The installation command will:

Ask you to choose between Vue.js or Blade templates
Publish configuration files
Publish migrations
Install the appropriate templates
Set up routes
Create example notification classes

3. Configure Your Environment

For Meta WhatsApp Business API (Default)

Add your WhatsApp Business API credentials to .env:

WHATSAPP_MODE=business

# Meta WhatsApp Business API
WHATSAPP_ACCESS_TOKEN=your_access_token_here
WHATSAPP_PHONE_NUMBER_ID=your_phone_number_id
WHATSAPP_ADMIN_PHONE_NUMBER=+1234567890
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_webhook_verify_token
WHATSAPP_WEBHOOK_URL=https://yourdomain.com/webhook/whatsapp
WHATSAPP_USE_MOCK_MODE=false

For WhatsAppJS Client

Add your WhatsApp Client configuration to .env:

WHATSAPP_MODE=client

# WhatsAppJS Client (Node.js Gateway)
WHATSAPP_CLIENT_URL=http://localhost:3000
WHATSAPP_CLIENT_TOKEN=your_bearer_token_here
WHATSAPP_CLIENT_ACCOUNT=default
WHATSAPP_CLIENT_WEBHOOK_SECRET=your_hmac_secret_here

Note: For WhatsAppJS Client mode, you'll need to run the Node.js gateway service separately. See the WhatsAppJS Client Setup section.

4. Update Your User Model

Add the required fields to your users table migration:

Schema::table('users', function (Blueprint $table) {
    $table->string('whatsapp_number')->nullable();
    $table->boolean('whatsapp_verified')->default(false);
    $table->timestamp('whatsapp_verified_at')->nullable();
    $table->string('whatsapp_verification_code')->nullable();
    $table->string('whatsapp_status')->nullable(); // active, unreachable, unknown
});

Add to your User model's $fillable array:

protected $fillable = [
    // ... existing fields
    'whatsapp_number',
    'whatsapp_verified',
    'whatsapp_verified_at',
    'whatsapp_verification_code',
    'whatsapp_status',
];

5. Run Migrations

php artisan migrate

Configuration

The package configuration is published to config/whatsapp-chat.php. Key settings:

return [
    // Provider selection
    'mode' => env('WHATSAPP_MODE', 'business'), // 'business' or 'client'

    // Business API config
    'access_token' => env('WHATSAPP_ACCESS_TOKEN'),
    'phone_number_id' => env('WHATSAPP_PHONE_NUMBER_ID'),
    'admin_phone_number' => env('WHATSAPP_ADMIN_PHONE_NUMBER'),
    'webhook_verify_token' => env('WHATSAPP_WEBHOOK_VERIFY_TOKEN'),
    'use_mock_mode' => env('WHATSAPP_USE_MOCK_MODE', true),

    // Client config
    'client' => [
        'base_url' => env('WHATSAPP_CLIENT_URL', 'http://localhost:3000'),
        'token' => env('WHATSAPP_CLIENT_TOKEN'),
        'default_account' => env('WHATSAPP_CLIENT_ACCOUNT', 'default'),
        'webhook_secret' => env('WHATSAPP_CLIENT_WEBHOOK_SECRET'),
    ],

    // User model configuration
    'user_model' => env('WHATSAPP_USER_MODEL', 'App\Models\User'),
    'admin_field' => env('WHATSAPP_ADMIN_FIELD', 'type'),
    'admin_value' => env('WHATSAPP_ADMIN_VALUE', 'admin'),

    // Re-engagement settings
    're_engagement' => [
        'enabled' => env('WHATSAPP_RE_ENGAGEMENT_ENABLED', true),
        'template_name' => env('WHATSAPP_RE_ENGAGEMENT_TEMPLATE', 'account_creation'),
    ],
];

Provider Modes

Meta WhatsApp Business API (business)

The default mode uses Meta's official WhatsApp Business Cloud API.

Features:

Official API with high reliability
Template message support
Media upload to Meta servers
Re-engagement template handling
Webhook verification via token

Setup:

Create a Meta Business account
Set up WhatsApp Business API
Get access token and phone number ID
Configure webhook URL
Set WHATSAPP_MODE=business in .env

WhatsAppJS Client (client)

Uses WhatsApp Web via a Node.js gateway service.

Features:

No API costs
Direct WhatsApp Web connection
QR code authentication
Real-time connection status
HMAC webhook security

Setup:

Install and run the Node.js gateway (see below)
Configure gateway URL and token
Set WHATSAPP_MODE=client in .env
Scan QR code to authenticate

WhatsAppJS Client Setup

Gateway Included in Package

✅ The WhatsAppJS Client gateway is included in this package in the whatsapp-client-gateway directory. You need to set it up and run it before testing Client mode.

Step 1: Navigate to Gateway Directory

The gateway is included in the package. Navigate to it:

cd vendor/devsfort/laravel-whatsapp-chat/whatsapp-client-gateway
# OR if you published it:
cd whatsapp-client-gateway

Step 2: Install Dependencies

If you have the gateway code, follow these steps:

1. Install Dependencies

2. Configure Gateway

Copy .env.example to .env:

PORT=3000
LARAVEL_URL=http://localhost:8000
LARAVEL_WEBHOOK_SECRET=your-hmac-secret-here
WHATSAPP_CLIENT_TOKEN=your-bearer-token-here
DEFAULT_ACCOUNT=default

Important: The WHATSAPP_CLIENT_TOKEN and LARAVEL_WEBHOOK_SECRET must match the values in your Laravel .env file:

WHATSAPP_CLIENT_TOKEN = WHATSAPP_CLIENT_TOKEN (in Laravel)
LARAVEL_WEBHOOK_SECRET = WHATSAPP_CLIENT_WEBHOOK_SECRET (in Laravel)

3. Run Gateway

# Development
npm run dev

# Production
npm start

4. Authenticate

Ensure gateway is running on port 3000 (or configured port)
Access the admin settings page: /admin/whatsapp-settings/{masterKey}
Click "Get QR Code" or "Restart & New QR"
Scan the QR code with your WhatsApp
Wait for connection confirmation

Gateway Requirements

The gateway service must provide these endpoints:

GET /health - Health check
GET /connection - Connection status
GET /qr - QR code for authentication
POST /send/text - Send text message
POST /send/media - Send media message
POST /mark-read - Mark message as read
POST /disconnect - Disconnect client
POST /restart - Restart client

All endpoints (except /health) require Bearer token authentication.

Gateway Webhooks

The gateway sends webhooks to Laravel at:

/api/whatsapp/client/incoming - Incoming messages
/api/whatsapp/client/status - Status updates
/api/whatsapp/client/connection - Connection events

All webhooks include HMAC signature in X-WhatsApp-Webhook-Signature header.

Usage

Sending Messages

use DevsFort\LaravelWhatsappChat\Services\WhatsAppService;

$whatsappService = app(WhatsAppService::class);

// Send text message
$result = $whatsappService->sendTextMessage('+1234567890', 'Hello!');

// Send attachment
$result = $whatsappService->sendAttachmentMessage(
    '+1234567890',
    'image',
    $mediaId, // For business mode
    'Caption here',
    $s3Url, // For client mode
    $fileSize
);

// Send OTP verification
$result = $whatsappService->sendOTPVerification('+1234567890', '123456');

Using Provider Directly

use DevsFort\LaravelWhatsappChat\WhatsApp\Contracts\WhatsAppProvider;

$provider = app(WhatsAppProvider::class);

// Check connection status
$health = $provider->health();

// Send message
$result = $provider->sendText('+1234567890', 'Hello!');

// Get provider name
$providerName = $provider->providerName(); // 'business' or 'client'

Notifications

The package integrates with Laravel's notification system:

use App\Notifications\MessageReceivedNotification;

$user->notify(new MessageReceivedNotification($messageData, $sender));

Create your notification class using the provided stubs:

php artisan make:notification MessageReceivedNotification

Then implement the toWhatsApp() method:

public function toWhatsApp($notifiable)
{
    return [
        'to' => $notifiable->whatsapp_number,
        'message' => 'Your message here'
    ];
}

API Endpoints

Chat Routes

GET /chat - Chat interface
GET /chat/conversations - Get conversation list
GET /chat/messages/{conversationId} - Get messages for conversation
POST /chat/send - Send a text message
POST /chat/send-attachment - Send an attachment
POST /chat/mark-read/{conversationId} - Mark messages as read
POST /chat/assign-number - Assign external number to user (admin only)
GET /chat/status - Get connection status (admin only)

Verification Routes

GET /profile/whatsapp-verification - Verification page
POST /profile/whatsapp-verification/send - Send OTP verification code
POST /profile/whatsapp-verification/verify - Verify OTP code
POST /profile/whatsapp-verification/remove - Remove WhatsApp number

Settings Routes (Admin, Master Key Protected)

GET /admin/whatsapp-settings/{masterKey} - Settings page
GET /admin/whatsapp-settings/qr-code - Get QR code (client mode)
POST /admin/whatsapp-settings/disconnect - Disconnect client (client mode)
POST /admin/whatsapp-settings/restart - Restart client (client mode)

Webhook Routes

GET /webhook/whatsapp - Meta API webhook verification
POST /webhook/whatsapp - Meta API webhook handler

Client Webhook Routes (API)

POST /api/whatsapp/client/incoming - Client incoming message webhook
POST /api/whatsapp/client/status - Client status update webhook
POST /api/whatsapp/client/connection - Client connection event webhook

Webhook Setup

Meta API Webhook

Set your webhook URL to: https://yourdomain.com/webhook/whatsapp
Use the verify token from your configuration
Subscribe to messages, message_deliveries, message_reads events

Client Webhook

The client webhook uses HMAC signature verification. Make sure:

WHATSAPP_CLIENT_WEBHOOK_SECRET matches in both Laravel and gateway
Gateway sends X-WhatsApp-Webhook-Signature header
Webhook URL is: https://yourdomain.com/api/whatsapp/client/incoming

Broadcasting Setup

The package uses Laravel Broadcasting for real-time features. Configure your broadcasting driver in .env:

BROADCAST_DRIVER=pusher
PUSHER_APP_ID=your_app_id
PUSHER_APP_KEY=your_app_key
PUSHER_APP_SECRET=your_app_secret
PUSHER_APP_CLUSTER=your_cluster

Console Commands

# Check WhatsApp token status
php artisan whatsapp:token-status

# Process queued messages
php artisan whatsapp:process-queue

# Process queue for specific number
php artisan whatsapp:process-queue --from=1234567890

Customization

User Model Configuration

If your User model uses different field names, configure them:

// config/whatsapp-chat.php
'user_model' => 'App\Models\User',
'admin_field' => 'role', // Instead of 'type'
'admin_value' => 'administrator', // Instead of 'admin'
'user_whatsapp_number_field' => 'phone', // Instead of 'whatsapp_number'
'user_whatsapp_verified_field' => 'phone_verified', // Instead of 'whatsapp_verified'

Notification Classes

Configure custom notification classes:

'notification_class' => 'App\Notifications\CustomWhatsAppNotification',
'notification_channel_class' => 'App\Notifications\Channels\CustomWhatsAppChannel',

Troubleshooting

Common Issues

"Provider not found"
- Ensure WHATSAPP_MODE is set correctly in .env
- Check that provider classes are autoloaded
- Run composer dump-autoload
"Client connection failed"
- Verify gateway is running on configured port
- Check WHATSAPP_CLIENT_TOKEN matches in both services
- Review gateway logs for errors
"Messages not appearing in real-time"
- Check your broadcasting configuration
- Ensure Pusher is properly configured
- Check browser console for JavaScript errors
"WhatsApp messages not sending"
- Verify your API credentials (business mode)
- Check if you're in mock mode
- Review the logs for API errors
- For client mode, ensure gateway is connected
"QR code not showing"
- Only available in client mode
- Check gateway connection status
- Try restarting the client via settings page

Debug Mode

Enable debug mode in your configuration:

'use_mock_mode' => true, // For development

Migration from Old Implementation

If you're upgrading from an older version:

Update your .env with new configuration options
Run php artisan config:clear
Update your routes to include new endpoints
Review breaking changes in CHANGELOG.md

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This package is open-sourced software licensed under the MIT license.

Support

For support, please open an issue on GitHub or contact us at support@devsfort.com.

Changelog

v3.0.0

✅ Added dual provider support (Meta API + WhatsAppJS Client)
✅ Implemented provider pattern for easy switching
✅ Added OTP verification system
✅ Enhanced attachment handling for both providers
✅ Added message queue for retry logic
✅ Implemented re-engagement support (Meta API)
✅ Added admin settings interface with QR code
✅ Enhanced webhook security (HMAC for client)
✅ Improved notification system integration
✅ Added status tracking for messages
✅ Better error handling and logging

v2.0.0

Added support for both Vue.js and Blade templates
Implemented external number assignment for admins
Separated registered and external conversations
Enhanced admin interface with better organization
Added installation command with template selection
Improved notification system
Better error handling and user feedback

v1.0.0

Initial release
Basic chat functionality
Vue.js components
Real-time messaging
WhatsApp verification

devsfort / laravel-whatsapp-chat

Maintainers

Details