README

A Laravel package for managing WhatsApp devices through WuzAPI. Connect multiple WhatsApp numbers to your application with multi-owner, multi-device support, Laravel notifications, and automatic webhook handling.

Table of Contents

• Requirements
• Installation
• Configuration
• Quick Start
• Core Concepts
• Usage
• Notification Channel
• Webhooks & Events
• Multi-Device Management
• Facade
• Testing
• License

Requirements

• PHP 8.2+
• Laravel 11 or 12
• A running WuzAPI instance

Installation

composer require jordanmiguel/laravel-whatsapp-wuz

Publish the config and migrations, then run them:

php artisan vendor:publish --tag="laravel-whatsapp-wuz-config"
php artisan vendor:publish --tag="laravel-whatsapp-wuz-migrations"
php artisan migrate

Configuration

Add these variables to your .env file:

WUZ_ENABLED=true
WUZ_API_URL=http://localhost:8080
WUZ_ADMIN_TOKEN=your-admin-token
WUZ_DEFAULT_COUNTRY_CODE=55
WUZ_DEBUG=false
WUZ_DEBUG_TO=

See config/wuz.php for additional options like custom table names, webhook path, and middleware.

Debug Mode

When WUZ_DEBUG=true, all outgoing messages are intercepted before sending. This lets you test the full pipeline in development/staging without messaging real users.

• With WUZ_DEBUG_TO set: All messages are redirected to that phone number, going through the same validation and sending pipeline.
• With WUZ_DEBUG_TO empty: Messages are logged via Log::info() and skipped entirely — no API call, no database record.

Quick Start

1. Add the trait and interface to your owner model (any Eloquent model that owns WhatsApp devices):

use JordanMiguel\Wuz\Contracts\HasWuzDevices as HasWuzDevicesContract;
use JordanMiguel\Wuz\Traits\HasWuzDevices;

class Clinic extends Model implements HasWuzDevicesContract
{
    use HasWuzDevices;
}

2. Create a device:

use JordanMiguel\Wuz\Actions\StoreDeviceAction;
use JordanMiguel\Wuz\Data\StoreDeviceData;

$device = app(StoreDeviceAction::class)->handle(
    owner: $clinic,
    data: new StoreDeviceData(name: 'Reception Phone'),
    createdBy: auth()->id(),
);

3. Get the QR code and scan it with WhatsApp:

use JordanMiguel\Wuz\Actions\GetDeviceStatusAction;

$status = app(GetDeviceStatusAction::class)->handle($device);
// $status->status   => 'connected' | 'qr' | 'disconnected'
// $status->qr_code  => base64 QR data (when status is 'qr')

4. Send a message:

use JordanMiguel\Wuz\Actions\SendMessageAction;
use JordanMiguel\Wuz\Data\SendMessageData;

app(SendMessageAction::class)->handle($device, new SendMessageData(
    phone: '5511999999999',
    type: 'text',
    message: 'Hello from Laravel!',
));

Core Concepts

Owners & Devices

Any Eloquent model can own WhatsApp devices by implementing the HasWuzDevices interface. This uses a polymorphic relationship, so a Clinic, Organization, Team, or User model can all own devices independently.

Each owner can have multiple devices. One device per owner is always marked as the default — this is the device used when sending notifications.

Device Lifecycle

Create → Connect → Scan QR → Connected → Send/Receive Messages

1. Create — Registers a new device with WuzAPI and stores it in your database
2. Connect — Initiates the connection (happens automatically on create)
3. Scan QR — Use GetDeviceStatusAction to retrieve the QR code for the user to scan with their WhatsApp mobile app
4. Connected — Once scanned, the device is connected and ready to send/receive messages
5. Send/Receive — Send messages via SendMessageAction, receive via webhooks

Usage

Managing Devices

Create a Device

use JordanMiguel\Wuz\Actions\StoreDeviceAction;
use JordanMiguel\Wuz\Data\StoreDeviceData;

$device = app(StoreDeviceAction::class)->handle(
    owner: $clinic,
    data: new StoreDeviceData(name: 'Reception Phone'),
    createdBy: auth()->id(),
);

The first device per owner is automatically set as default.

Check Device Status / Get QR Code

use JordanMiguel\Wuz\Actions\GetDeviceStatusAction;

$status = app(GetDeviceStatusAction::class)->handle($device);
// $status->status   => 'connected' | 'qr' | 'disconnected'
// $status->qr_code  => base64 QR data (when status is 'qr')

Disconnect a Device

use JordanMiguel\Wuz\Actions\DisconnectDeviceAction;

app(DisconnectDeviceAction::class)->handle($device);

Delete a Device

use JordanMiguel\Wuz\Actions\DeleteDeviceAction;

app(DeleteDeviceAction::class)->handle($device);

When you delete the default device, the next oldest device is automatically promoted to default.

Sending Messages

use JordanMiguel\Wuz\Actions\SendMessageAction;
use JordanMiguel\Wuz\Data\SendMessageData;

$message = app(SendMessageAction::class)->handle($device, new SendMessageData(
    phone: '5511999999999',
    type: 'text',
    message: 'Hello from Laravel!',
));

Supported message types: text, image, video, document, button.

Notification Channel

Send WhatsApp messages through Laravel's notification system.

Define a Notification

use JordanMiguel\Wuz\Notifications\WuzMessage;

class AppointmentReminder extends Notification
{
    public function via($notifiable): array
    {
        return ['wuz'];
    }

    public function toWuz($notifiable): WuzMessage
    {
        return WuzMessage::create('Your appointment is tomorrow at 10am.');
    }
}

Set Up the Notifiable Model

The notifiable model needs the InteractsWithWuz trait to resolve which device should send the message:

use JordanMiguel\Wuz\Traits\InteractsWithWuz;

class ClientProfile extends Model
{
    use InteractsWithWuz, Notifiable;

    public function routeNotificationForWhatsapp(): ?string
    {
        return $this->phone;
    }

    public function resolveWuzOwner(): mixed
    {
        return $this->clinic;
    }
}

The channel resolves the device by calling resolveWuzOwner() on the notifiable, then uses that owner's default device to send the message.

Configuration — Selective Logging and Event-Driven Messages

config/wuz.php exposes two knobs for the webhook pipeline:

'logging' => [
    // Allowlist of event types to insert into wuz_callback_logs.
    // Use ['*'] for all, [] for none, or any mix of WuzEventType cases / strings.
    'event_types' => \JordanMiguel\Wuz\Enums\WuzEventType::defaultLoggingTypes(),
],

'webhook_event' => [
    // Allowlist of event types that dispatch the generic WebhookReceived event.
    'event_types' => \JordanMiguel\Wuz\Enums\WuzEventType::defaultDispatchTypes(),
],

Defaults are conservative. MESSAGE is not logged by default — opt in if you want raw payload rows. Lifecycle, pairing, and error events are logged so you have a forensic trail when things break.

Inbound messages are event-driven. Subscribe to JordanMiguel\Wuz\Events\MessageReceived and persist however your domain needs:

class StoreIncomingMessage
{
    public function handle(\JordanMiguel\Wuz\Events\MessageReceived $event): void
    {
        // $event->device, $event->type, $event->chatJid,
        // $event->senderJid, $event->content, $event->payload (raw)
    }
}

MessageSent fires symmetrically for outbound (HTTP 2xx WUZ responses only).

For media: call WuzService::downloadImage/downloadVideo/downloadDocument from inside a MessageReceived listener. The package no longer auto-downloads.

See UPGRADING.md for the v1→v2 migration guide.

Webhooks & Events

Incoming WhatsApp events are received at POST /api/wuz/webhook/{token} (configurable in config/wuz.php).

Handled Events

Logging and WebhookReceived dispatch are gated independently — both default sets are conservative but distinct (notably, MESSAGE dispatches by default but is not logged by default). See the "Configuration — Selective Logging and Event-Driven Messages" section above.

Listening to Events

Register listeners in your EventServiceProvider or use Laravel's event discovery:

use JordanMiguel\Wuz\Events\MessageReceived;

class HandleIncomingMessage
{
    public function handle(MessageReceived $event): void
    {
        $device    = $event->device;
        $type      = $event->type;       // 'text' | 'image' | 'video' | 'document'
        $chatJid   = $event->chatJid;
        $senderJid = $event->senderJid;
        $content   = $event->content;    // body text or media caption / filename
        $payload   = $event->payload;    // raw WUZ webhook payload
        // Process incoming message...
    }
}

Multi-Device Management

Each owner can have multiple WhatsApp devices. The package enforces that exactly one device per owner is the default.

Facade

use JordanMiguel\Wuz\Facades\Wuz;

$service = Wuz::make($device); // device-scoped WuzService
$admin   = Wuz::admin();       // admin-scoped WuzService

Testing

Mock the WuzAPI in your application tests using Laravel's HTTP fakes:

Http::fake([
    '*/session/status' => Http::response(['data' => ['loggedIn' => true]], 200),
    '*/chat/send/text' => Http::response(['data' => ['sent' => true]], 200),
]);

Run the package tests:

composer test

License

MIT