emam/whatsapp-manager

A framework-agnostic PHP package for WhatsApp integration. Supports multiple drivers (Official Meta, Textly, Ultramsg, WaPilot), dynamic configuration, webhooks, and unified messaging API.

v1.0.0 2025-11-29 19:35 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.10

Requires (Dev)

• friendsofphp/php-cs-fixer: ^3.0
• pestphp/pest: ^2.0 || ^3.0
• phpstan/phpstan: ^1.10

MIT

• Hamada Emam

• php
• api
• manager
• sdk
• messaging
• driver
• meta
• business
• whatsapp
• framework-agnostic

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('[phone]',
    WhatsappMessage::create('Hello from WhatsApp Manager!')
);

// 4. Send Media Message (Image)
$message = WhatsappMessage::create()
    ->image('https://example.com/image.png', 'Check this out!');
$manager->driver()->send('[phone]', $message);

// 5. Send Location
$message = WhatsappMessage::create()
    ->location(25.2048, 55.2708, 'Burj Khalifa', '1 Sheikh Mohammed bin Rashid Blvd');
$manager->driver()->send('[phone]', $message);

// 6. Upload Media & Send
$driver = $manager->driver('official');
$upload = $driver->uploadMedia('/path/to/image.jpg', 'image');
$mediaId = $upload['id'];

$message = WhatsappMessage::create()
    ->image($mediaId, 'Uploaded image');
$driver->send('[phone]', $message);

// 7. Reply to Message
$message = WhatsappMessage::create('This is a reply')
    ->reply('wamid.HBg...');
$manager->driver()->send('[phone]', $message);

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

$manager->driver('official')->send('[phone]', $message);

// 9. Send Interactive Button Message
$manager->sendButtonMessage('123456')
    ->to('[phone]')
    ->withBody('Do you confirm your appointment for tomorrow at 3 PM?')
    ->addButton('confirm', '✅ Confirm')
    ->addButton('reschedule', '🔄 Reschedule')
    ->addButton('cancel', '❌ Cancel')
    ->withFooter('Please select an option')
    ->send();

// 10. Send Interactive List Message
$manager->sendListMessage('123456')
    ->to('[phone]')
    ->withButtonText('View Products')
    ->withBody('Our featured products:')
    ->withHeader('Digital Catalog')
    ->startSection('Laptops')
        ->addRow('laptop-pro', 'MacBook Pro', '16" - 32GB RAM - 1TB SSD')
        ->addRow('laptop-air', 'MacBook Air', '13" - M2 Chip - 8GB RAM')
    ->endSection()
    ->startSection('Smartphones')
        ->addRow('iphone-15', 'iPhone 15 Pro', '48MP Camera - 5G')
        ->addRow('samsung-s23', 'Samsung S23', '120Hz AMOLED Display')
    ->endSection()
    ->send();

🛠️ Advanced Usage

Template Management

// Get all templates
$templates = $manager->driver('official')->getTemplates(100);

// Create a template
$template = $manager->driver('official')->createTemplate(
    'order_confirmation',
    'UTILITY',
    'en_US',
    [
        ['type' => 'BODY', 'text' => 'Your order {{1}} has been confirmed.']
    ]
);

// Delete a template
$manager->driver('official')->deleteTemplate('order_confirmation');

Template Builder (Fluent API)

use Emam\WhatsappManager\Templates\TemplateBuilder;

$driver = $manager->driver('official');

// Create a complete template with fluent API
$template = TemplateBuilder::create($driver)
    ->utility()
    ->name('order_confirmation')
    ->language('en_US')
    ->header('Order Confirmed', 'text')
    ->body('Your order {{1}} has been confirmed. Delivery: {{2}}')
    ->footer('Thank you for your order!')
    ->quickReplyButton('Track Order')
    ->quickReplyButton('Contact Support')
    ->build();

// Marketing template with image
$template = TemplateBuilder::create($driver)
    ->marketing()
    ->name('summer_sale')
    ->language('en_US')
    ->header('', 'image')  // Image header
    ->body('Summer Sale! Get {{1}}% off. Use code: {{2}}')
    ->footer('Valid until end of month')
    ->urlButton('Shop Now', 'https://example.com/sale')
    ->build();

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

🔌 Adding Custom Drivers

The package provides a complete scaffolding system to easily add new WhatsApp providers:

Quick Start

# Generate a new driver scaffold
php bin/generate-driver.php ProviderName

# This creates:
# - src/Drivers/ProviderNameDriver.php (driver class)
# - tests/Unit/ProviderNameDriverTest.php (test file)
# - Step-by-step integration instructions

What You Get

• ✅ Complete driver template with all required methods
• ✅ Pre-configured tests ready to run
• ✅ Step-by-step instructions for integration
• ✅ Best practices built-in
• ✅ Type-safe implementation

Example: Adding a New Provider

# 1. Generate scaffold
php bin/generate-driver.php Twilio

# 2. Implement provider-specific logic
# Edit: src/Drivers/TwilioDriver.php

# 3. Run tests
php vendor/bin/pest tests/Unit/TwilioDriverTest.php

# 4. Use your driver
$manager->driver('twilio')->send('[phone]', $message);

Documentation

• 📖 Complete Driver Development Guide
• ✅ Driver Development Checklist
• 🔧 Driver Generator Tool

🤝 Contributing

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

📄 License

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