PHPackages                             devsfort/laravel-whatsapp-chat - 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. [API Development](/categories/api)
4. /
5. devsfort/laravel-whatsapp-chat

ActiveLibrary[API Development](/categories/api)

devsfort/laravel-whatsapp-chat
==============================

A comprehensive WhatsApp integration package for Laravel with dual provider support (Meta API & WhatsAppJS Client), real-time chat, OTP verification, notifications, and attachment handling

v2.0.0-alpha(7mo ago)126↓100%MITPHPPHP >=8.1

Since Sep 29Pushed 3mo agoCompare

[ Source](https://github.com/hahmad748/laravel-whatsapp-chat)[ Packagist](https://packagist.org/packages/devsfort/laravel-whatsapp-chat)[ RSS](/packages/devsfort-laravel-whatsapp-chat/feed)WikiDiscussions master Synced 1mo ago

READMEChangelog (1)Dependencies (14)Versions (2)Used By (0)

Laravel WhatsApp Chat Package
=============================

[](#laravel-whatsapp-chat-package)

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
--------

[](#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
-------------------------------------

[](#️-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](#whatsappjs-client-setup) section below.

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

Installation
------------

[](#installation)

### 1. Install via Composer

[](#1-install-via-composer)

```
composer require devsfort/laravel-whatsapp-chat
```

### 2. Run the Installation Command

[](#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

[](#3-configure-your-environment)

#### For Meta WhatsApp Business API (Default)

[](#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

[](#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](#whatsappjs-client-setup) section.

### 4. Update Your User Model

[](#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

[](#5-run-migrations)

```
php artisan migrate
```

Configuration
-------------

[](#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
--------------

[](#provider-modes)

### Meta WhatsApp Business API (business)

[](#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:**

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

### WhatsAppJS Client (client)

[](#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:**

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

WhatsAppJS Client Setup
-----------------------

[](#whatsappjs-client-setup)

### Gateway Included in Package

[](#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

[](#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

[](#step-2-install-dependencies)

If you have the gateway code, follow these steps:

#### 1. Install Dependencies

[](#1-install-dependencies)

#### 2. Configure Gateway

[](#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

[](#3-run-gateway)

```
# Development
npm run dev

# Production
npm start
```

#### 4. Authenticate

[](#4-authenticate)

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

### Gateway Requirements

[](#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

[](#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
-----

[](#usage)

### Sending Messages

[](#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

[](#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

[](#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
-------------

[](#api-endpoints)

### Chat Routes

[](#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

[](#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)

[](#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

[](#webhook-routes)

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

### Client Webhook Routes (API)

[](#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
-------------

[](#webhook-setup)

### Meta API Webhook

[](#meta-api-webhook)

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

### Client Webhook

[](#client-webhook)

The client webhook uses HMAC signature verification. Make sure:

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

Broadcasting Setup
------------------

[](#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
----------------

[](#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
-------------

[](#customization)

### User Model Configuration

[](#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

[](#notification-classes)

Configure custom notification classes:

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

Troubleshooting
---------------

[](#troubleshooting)

### Common Issues

[](#common-issues)

1. **"Provider not found"**

    - Ensure `WHATSAPP_MODE` is set correctly in `.env`
    - Check that provider classes are autoloaded
    - Run `composer dump-autoload`
2. **"Client connection failed"**

    - Verify gateway is running on configured port
    - Check `WHATSAPP_CLIENT_TOKEN` matches in both services
    - Review gateway logs for errors
3. **"Messages not appearing in real-time"**

    - Check your broadcasting configuration
    - Ensure Pusher is properly configured
    - Check browser console for JavaScript errors
4. **"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
5. **"QR code not showing"**

    - Only available in client mode
    - Check gateway connection status
    - Try restarting the client via settings page

### Debug Mode

[](#debug-mode)

Enable debug mode in your configuration:

```
'use_mock_mode' => true, // For development
```

Migration from Old Implementation
---------------------------------

[](#migration-from-old-implementation)

If you're upgrading from an older version:

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

Contributing
------------

[](#contributing)

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

License
-------

[](#license)

This package is open-sourced software licensed under the [MIT license](https://opensource.org/licenses/MIT).

Support
-------

[](#support)

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

Changelog
---------

[](#changelog)

### v3.0.0

[](#v300)

- ✅ 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

[](#v200)

- 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

[](#v100)

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

###  Health Score

31

—

LowBetter than 68% of packages

Maintenance73

Regular maintenance activity

Popularity10

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity30

Early-stage or recently created project

 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

Unknown

Total

1

Last Release

225d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/8de8368b1c33b278da76e212fc6922aeb9dce7c5fd916b40071e127b0e81466a?d=identicon)[devsfort](/maintainers/devsfort)

---

Top Contributors

[![hahmad748](https://avatars.githubusercontent.com/u/42300494?v=4)](https://github.com/hahmad748 "hahmad748 (13 commits)")

---

Tags

apilaravelbusinesscloudreal-timemessagingpusherinertiachatwhatsappBroadcastingvue

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/devsfort-laravel-whatsapp-chat/health.svg)

```
[![Health](https://phpackages.com/badges/devsfort-laravel-whatsapp-chat/health.svg)](https://phpackages.com/packages/devsfort-laravel-whatsapp-chat)
```

###  Alternatives

[roots/acorn

Framework for Roots WordPress projects built with Laravel components.

9682.1M97](/packages/roots-acorn)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k12.1M99](/packages/laravel-pulse)[flat3/lodata

OData v4.01 Producer for Laravel

96320.9k](/packages/flat3-lodata)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

255.2k](/packages/aedart-athenaeum)[essa/api-tool-kit

set of tools to build an api with laravel

52680.5k](/packages/essa-api-tool-kit)[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)