README

WhatsApp Business API (Meta Cloud API) integration for Laravel. Send text messages, PDFs, and generate secure time-limited share links for any model.

Installation

composer require tizfai/laravel-whatsapp

Publish config and run migration:

php artisan vendor:publish --tag=whatsapp-config
php artisan migrate

Configuration

Add to your .env:

WHATSAPP_ACCESS_TOKEN=EAAG...your_system_user_token
WHATSAPP_PHONE_NUMBER_ID=984998221371272
WHATSAPP_BUSINESS_ACCOUNT_ID=1615131750010820
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your_custom_verify_token_here
WHATSAPP_API_VERSION=v21.0
WHATSAPP_LINK_EXPIRY_HOURS=24
WHATSAPP_MAX_ACCESS_COUNT=3

Usage

Send Text Message

use Tizfai\LaravelWhatsApp\Facades\WhatsApp;

$result = WhatsApp::sendText('+8801711111111', 'Hello from DocFai!');

if ($result['success']) {
    echo $result['message_id'];
}

Send PDF Document

$result = WhatsApp::sendDocument(
    phone: '+8801711111111',
    fileUrl: 'https://your-wasabi-url.com/prescription.pdf',
    filename: 'prescription_001.pdf',
    caption: 'Your prescription'
);

Send Text + PDF Together

$result = WhatsApp::sendDocumentWithText(
    toPhone: '+8801711111111',
    fileUrl: 'https://storage.com/prescription.pdf',
    filename: 'prescription.pdf',
    textMessage: '🏥 Your prescription is attached.',
    caption: 'DocFai Prescription'
);

Send Template Message

$result = WhatsApp::sendTemplate(
    toPhone: '+8801711111111',
    templateName: 'prescription_ready',
    parameters: [
        ['type' => 'text', 'text' => 'Kamal'],
        ['type' => 'text', 'text' => 'RX-2026-001'],
    ],
    languageCode: 'en'
);

Secure Share Links

Generate time-limited, access-counted secure links for any Eloquent model.

Create Share Link Only

$share = WhatsApp::createShareLink(
    model: $prescription,
    recipientPhone: '+8801711111111',
    recipientName: 'Kamal Tizfai',
    expiryHours: 24,     // optional, uses config default
    maxAccess: 3,         // optional, uses config default
    metadata: ['shared_by' => auth()->id()]
);

echo $share->getShareUrl(); // https://yourapp.com/wa-view/{token}
echo $share->isValid();     // true/false

Create Share Link AND Send via WhatsApp

$result = WhatsApp::sendShareLink(
    model: $prescription,
    recipientPhone: '+8801711111111',
    recipientName: 'Kamal Tizfai',
    messageBody: "🏥 Your prescription is ready:\n{URL}\n\nValid 24h | Max 3 views",
    expiryHours: 24,
    maxAccess: 3
);

$share = $result['share']; // WhatsAppShare model instance

Access the Share in Your Controller

Add a public route in your app:

// routes/web.php
Route::get('/wa-view/{token}', [YourPrescriptionViewController::class, 'show']);

// YourPrescriptionViewController.php
use Tizfai\LaravelWhatsApp\Models\WhatsAppShare;

public function show(string $token, Request $request)
{
    $share = WhatsAppShare::where('secure_token', $token)->firstOrFail();

    if (!$share->isValid()) {
        abort(403, 'Link has expired or access limit reached');
    }

    $share->recordAccess([
        'ip' => $request->ip(),
        'user_agent' => $request->userAgent(),
    ]);

    $prescription = $share->shareable; // Polymorphic - returns your model
    return view('prescriptions.view', compact('prescription'));
}

Webhook Setup

The package automatically registers these routes:

• GET /api/webhooks/whatsapp - Meta webhook verification
• POST /api/webhooks/whatsapp - Delivery status & incoming messages

In Meta Developer Console:

1. Go to your app → WhatsApp → Configuration
2. Webhook URL: https://yourdomain.com/api/webhooks/whatsapp
3. Verify token: same value as WHATSAPP_WEBHOOK_VERIFY_TOKEN
4. Subscribe to: messages

Artisan Commands

# Clean up expired shares (default: older than 30 days)
php artisan whatsapp:clean-shares

# Preview without deleting
php artisan whatsapp:clean-shares --dry-run

# Custom retention period
php artisan whatsapp:clean-shares --days=7

Schedule in app/Console/Kernel.php:

$schedule->command('whatsapp:clean-shares')->daily();

API Reference

License

MIT