README

WhatsApp Cloud API Notification Channel for Laravel.

Installation

composer require saythanks/laravel-whatsapp

Publish the config file:

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

Configuration

Add these to your .env:

WHATSAPP_ACCESS_TOKEN=your-meta-access-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_BUSINESS_ACCOUNT_ID=your-business-account-id
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-webhook-verify-token

Optional settings:

WHATSAPP_API_VERSION=v22.0
WHATSAPP_API_BASE_URL=https://graph.facebook.com
WHATSAPP_DELIVERY_ENABLED=true
WHATSAPP_LOG_STATUS_UPDATES=false
WHATSAPP_STORE_CACHE_ENABLED=false
WHATSAPP_STORE_CACHE_TTL=86400

Usage

Sending Notifications

Add the routing method to your notifiable model:

public function routeNotificationForWhatsapp($notification)
{
    return $this->phone_number; // E.164 format without +
}

Create a notification with a toWhatsapp method:

use LaravelWhatsapp\Facades\LaravelWhatsapp;

class VoucherCreated extends Notification
{
    public function via($notifiable)
    {
        return ['whatsapp'];
    }

    // Text message (within 24h customer service window)
    public function toWhatsapp($notifiable)
    {
        return LaravelWhatsapp::message('Your voucher is ready!')
            ->userReferenceId('voucher-' . $this->voucher->getKey());
    }
}

Template Messages

For business-initiated conversations (outside 24h window), use template messages:

public function toWhatsapp($notifiable)
{
    return LaravelWhatsapp::template('voucher_created', 'en')
        ->bodyParameters([
            ['type' => 'text', 'text' => $recipientName],
            ['type' => 'text', 'text' => $voucherValue],
        ])
        ->userReferenceId('voucher-' . $this->voucher->getKey());
}

Templates must be pre-approved in your Meta Business Manager.

Webhooks

The package provides form requests for handling Meta webhook callbacks:

Status Updates (delivery reports):

use LaravelWhatsapp\Requests\WhatsappStatusUpdateRequest;

public function handleStatusUpdate(WhatsappStatusUpdateRequest $request)
{
    $dto = $request->toDto();
    // $dto->messageId, $dto->status, $dto->recipientId, $dto->getStatusEnum()
}

Incoming Messages (replies):

use LaravelWhatsapp\Requests\WhatsappIncomingMessageRequest;

public function handleIncomingMessage(WhatsappIncomingMessageRequest $request)
{
    $dto = $request->toDto();
    // $dto->messageId, $dto->from, $dto->textBody, $dto->senderName
}

Webhook Verification (Meta requires a GET verification handshake):

public function verify(Request $request)
{
    if ($request->query('hub_verify_token') === config('whatsapp.webhook_verify_token')) {
        return response($request->query('hub_challenge'), 200);
    }
    return response('Forbidden', 403);
}

Message Types

Message Status Enum

Testing

composer test

License

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

ngrok http https://website.test --host-header=website.test