README

A comprehensive Laravel package for seamless integration with the Official WhatsApp Cloud API.

Features

Multi-account support (config-based or database-driven)
Fluent API for sending all message types (text, image, video, document, audio, sticker, location, contacts, interactive, template, reaction)
Template management (list, create, update, delete)
Webhook handling with automatic signature verification
Laravel events for incoming messages and status updates
Database logging for API requests, messages, webhooks, and templates
Laravel notification channel for WhatsApp
Artisan commands for syncing templates and message statuses

Requirements

PHP 8.2+
Laravel 11 or 12

Installation

Install the package via Composer:

composer require laraditz/whatsapp

Publish the config file:

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

Publish and run migrations (required for logging and database account driver):

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

Configuration

Add the following to your .env file:

WHATSAPP_ACCESS_TOKEN=your-access-token
WHATSAPP_PHONE_NUMBER_ID=your-phone-number-id
WHATSAPP_BUSINESS_ACCOUNT_ID=your-business-account-id
WHATSAPP_WEBHOOK_VERIFY_TOKEN=your-verify-token
WHATSAPP_WEBHOOK_SECRET=your-app-secret

See Configuration Guide for multi-account setup and all available options.

Quick Start

Sending Messages

use Laraditz\Whatsapp\Facades\Whatsapp;

// Text message
Whatsapp::message()->to('60123456789')->text('Hello!')->send();

// Image
Whatsapp::message()
    ->to('60123456789')
    ->image(link: 'https://example.com/photo.jpg', caption: 'Check this out')
    ->send();

// Template message
Whatsapp::message()
    ->to('60123456789')
    ->template(name: 'order_update', language: 'en')
    ->component(type: 'body', parameters: [
        ['type' => 'text', 'text' => 'ORDER-123'],
    ])
    ->send();

Managing Templates

// List all templates
$response = Whatsapp::template()->list();

// Create a template
Whatsapp::template()->create(
    name: 'welcome_message',
    language: 'en',
    category: 'UTILITY',
    components: [
        ['type' => 'BODY', 'text' => 'Welcome, {{1}}!'],
    ],
);

Laravel Notification

use Illuminate\Notifications\Notification;
use Laraditz\Whatsapp\Channels\WhatsappChannel;
use Laraditz\Whatsapp\Messages\WhatsappMessage;

class OrderShipped extends Notification
{
    public function via($notifiable): array
    {
        return [WhatsappChannel::class];
    }

    public function toWhatsapp($notifiable): WhatsappMessage
    {
        return WhatsappMessage::create()
            ->template(name: 'order_update', language: 'en')
            ->component(type: 'body', parameters: [
                ['type' => 'text', 'text' => 'ORDER-123'],
            ]);
    }
}

// Send it
$user->notify(new OrderShipped($order));

Multi-Account

// Switch account
Whatsapp::account('support')->message()->to('60123456789')->text('Hi from support')->send();

Artisan Commands

Command	Description
`php artisan whatsapp:sync-templates`	Sync all templates from the WhatsApp API to the local database
`php artisan whatsapp:sync-templates --account=support`	Sync templates for a specific account
`php artisan whatsapp:sync-messages`	Sync message statuses for messages not yet delivered or read
`php artisan whatsapp:sync-messages --account=default --since=2024-01-01`	Sync messages for a specific account and date range

Documentation

Configuration Guide - Account drivers, logging, and all config options
Sending Messages - All message types with examples
Template Management - CRUD operations and syncing
Webhooks & Events - Webhook setup and Laravel event handling
Notifications - Laravel notification channel integration
Error Handling - Exception types and handling patterns

Testing

composer test

Changelog

Please see CHANGELOG for more information what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please email raditzfarhan@gmail.com instead of using the issue tracker.

Credits

License

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

laraditz / whatsapp

Maintainers

Details