saythanks/laravel-whatsapp

WhatsApp Cloud API Notification Channel for Laravel

v0.1.1 2026-04-10 12:09 UTC

Requires

• php: >=8.2
• illuminate/contracts: >=10.0
• illuminate/http: >=10.0
• illuminate/notifications: >=10.0
• illuminate/support: >=10.0

Requires (Dev)

• larastan/larastan: ^2.0 || ^3.0
• laravel/pint: ^1.14
• nunomaduro/collision: ^7.0 || ^8.0
• orchestra/testbench: ^9.0 || ^10.0
• pestphp/pest: ^2.0 || ^3.0
• pestphp/pest-plugin-arch: ^2.0 || ^3.0
• pestphp/pest-plugin-laravel: ^2.0 || ^3.0
• phpstan/extension-installer: ^1.4
• phpstan/phpstan-deprecation-rules: ^1.0 || ^2.0
• phpstan/phpstan-phpunit: ^1.0 || ^2.0
• spatie/laravel-ray: ^1.35

MIT

• Tom Pretorius

• laravel
• whatsapp
• laravel-whatsapp
• saythanks

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

Type	Use Case	Method
Text	Within 24h customer service window	LaravelWhatsapp::message('text')
Template	Business-initiated (any time)	LaravelWhatsapp::template('name', 'lang')

Message Status Enum

Status	Description
sent	Message sent to WhatsApp servers
delivered	Message delivered to recipient
read	Message read by recipient
failed	Message delivery failed

Testing

composer test

License

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

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