README

A robust, framework-agnostic PHP package for integrating WhatsApp Business API into your applications. It supports multiple drivers, dynamic configuration, webhooks, and a unified messaging API.

🌟 Features

Multi-Driver Support:
- ✅ Official Meta WhatsApp Business API
- ✅ Textly
- ✅ Ultramsg
- ✅ WaPilot
- 🔌 Custom Drivers: Easily extendable
Unified API: Send messages using a consistent interface regardless of the driver.
Dynamic Configuration: Load config from arrays, JSON, or environment variables.
Webhook Handling: Secure validation (HMAC signature) and processing of incoming messages.
Publishing System: Publish config and drivers to your project for customization.
Framework Agnostic: Works with Laravel, Symfony, CodeIgniter, or native PHP.
Type Safe: Strict types and comprehensive error handling.

📦 Installation

Install via Composer:

composer require emam/whatsapp-manager

⚙️ Configuration

1. Publish Configuration

Run the publishing command to create a configuration file in your project:

php vendor/bin/publish.php config

This creates config/whatsapp.php.

2. Set Environment Variables

Add your credentials to your .env file:

WHATSAPP_DRIVER=official

# Official Meta Driver
WHATSAPP_OFFICIAL_TOKEN=your_access_token
WHATSAPP_OFFICIAL_PHONE_ID=your_phone_number_id
WHATSAPP_OFFICIAL_VERIFY_TOKEN=your_verify_token
WHATSAPP_OFFICIAL_APP_SECRET=your_app_secret

# Textly Driver
WHATSAPP_TEXTLY_TOKEN=your_token

# Ultramsg Driver
WHATSAPP_ULTRAMSG_ID=your_instance_id
WHATSAPP_ULTRAMSG_TOKEN=your_token

# WaPilot Driver
WHATSAPP_WAPILOT_ID=your_instance_id
WHATSAPP_WAPILOT_TOKEN=your_token

🚀 Usage

Sending Messages

use Emam\WhatsappManager\Config\ConfigManager;
use Emam\WhatsappManager\WhatsappManager;
use Emam\WhatsappManager\Messages\WhatsappMessage;

// 1. Load Configuration
$config = new ConfigManager(require 'config/whatsapp.php');

// 2. Create Manager
$manager = new WhatsappManager($config->all());

// 3. Send Text Message
$response = $manager->driver()->send('+1234567890',
    WhatsappMessage::create('Hello from WhatsApp Manager!')
);

// 4. Send Template Message (Official Driver)
$message = WhatsappMessage::create()
    ->template('hello_world', 'en_US');

$manager->driver('official')->send('+1234567890', $message);

Handling Webhooks

The package provides a secure WebhookValidator to handle incoming webhooks.

Native PHP Example:

use Emam\WhatsappManager\Webhook\WebhookValidator;

$validator = new WebhookValidator($config->all());

try {
    // Validate request
    $validator->validate(
        $_SERVER['REQUEST_URI'],
        $_GET,
        json_decode(file_get_contents('php://input'), true),
        getallheaders()
    );

    // Process webhook
    $payload = json_decode(file_get_contents('php://input'), true);
    $result = $manager->driver()->handleWebhook($payload);

} catch (WebhookException $e) {
    http_response_code(403);
    echo $e->getMessage();
}

🛠️ Advanced Usage

Custom Drivers

You can easily add your own driver:

use Emam\WhatsappManager\Contracts\Driver;

class MyCustomDriver implements Driver {
    // Implement methods...
}

$manager->extend('custom', function() {
    return new MyCustomDriver();
});

$manager->driver('custom')->send(...);

Publishing Drivers

You can publish driver files to your project to modify them:

php vendor/bin/publish.php driver Official

This creates app/WhatsApp/Drivers/OfficialDriver.php which you can customize.

🧪 Testing

Run the test suite:

composer test

🤝 Contributing

Contributions are welcome! Please see CONTRIBUTING.md for details.

📄 License

The MIT License (MIT). Please see License File for more information.

emam / whatsapp-manager

Maintainers

Details