Download the PHP package jordanmiguel/laravel-whatsapp-wuz without Composer

Laravel WhatsApp Wuz

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

Publish the config and migrations, then run them:

Configuration

Add these variables to your .env file:

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

2. Create a device:

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

4. Send a message:

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

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

The first device per owner is automatically set as default.

Check Device Status / Get QR Code

Disconnect a Device

Delete a Device

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

Sending Messages

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

Notification Channel

Send WhatsApp messages through Laravel's notification system.

Define a Notification

Set Up the Notifiable Model

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

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:

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:

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:

Multi-Device Management

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

Facade

Testing

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

Run the package tests:

License

MIT