🚀 Complete Installation

This guide will take you step by step through the installation and configuration of the WhatsApp API Manager package for Laravel.

📋 Prerequisites

Before installing the package, you'll need:

• PHP 8.2 or higher
• Laravel 12 or higher
• A WhatsApp Business API Cloud account

🔧 Installation Steps

1. Install the Package

Install the package through Composer:

composer require scriptdevelop/whatsapp-manager

2. Publish Configuration Files

This command will publish the package's base configuration files:

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

This will create:

• config/whatsapp.php - Main package configuration
• Updates to config/logging.php - WhatsApp logging channel

3. Configure Logging Channel

Add the WhatsApp channel to your config/logging.php file:

'channels' => [
    // ... other channels

    'whatsapp' => [
        'driver' => 'daily',
        'path' => storage_path('logs/whatsapp.log'),
        'level' => 'debug',
        'days' => 7,
        'tap' => [\ScriptDevelop\WhatsappManager\Logging\CustomizeFormatter::class],
    ],
],

4. Publish Migrations (Optional)

Migrations will run automatically with php artisan migrate. If you want to customize them, publish them first:

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

5. Publish Webhook Routes

This step is required to receive incoming message notifications:

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

6. Exclude Webhook from CSRF

Add the webhook route to the CSRF exceptions in bootstrap/app.php:

->withMiddleware(function (Middleware $middleware) {
    $middleware->validateCsrfTokens(except: [
        '/whatsapp-webhook',
    ]);
})

7. Configure Environment Variables

Add these variables to your .env file:

# WhatsApp API Configuration
WHATSAPP_API_URL=https://graph.facebook.com
WHATSAPP_API_VERSION=v21.0
WHATSAPP_VERIFY_TOKEN=your-verify-token
WHATSAPP_USER_MODEL=App\Models\User
WHATSAPP_BROADCAST_CHANNEL_TYPE=private

# Optional variables for OAuth
META_CLIENT_ID=123456789012345
META_CLIENT_SECRET=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
META_REDIRECT_URI=https://yourdomain.com/meta/callback
META_SCOPES=whatsapp_business_management,whatsapp_business_messaging

🗃️ Database Configuration

1. Run Migrations

Execute the migrations to create the necessary tables:

php artisan migrate

This will create the following tables:

• whatsapp_phones - WhatsApp Business phone numbers
• whatsapp_contacts - Contacts
• whatsapp_messages - Sent and received messages
• whatsapp_templates - Message templates
• And more...

2. Seed Languages Table

Seeders are required for working with WhatsApp templates:

# Publish seeders
php artisan vendor:publish --tag=whatsapp-seeders

# Run language seeder
php artisan db:seed --class=WhatsappTemplateLanguageSeeder

📁 Media Files Configuration

1. Directory Structure

The package needs a folder structure to store media files:

storage/app/public/whatsapp/
├── audios/
├── documents/
├── images/
├── stickers/
└── videos/

2. Create Structure Automatically (Recommended)

Publish the media structure with a single command:

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

3. Create Symbolic Link

To make files publicly accessible:

php artisan storage:link

🔗 Webhook Configuration in Meta

To receive incoming messages, configure the webhook in Meta Developers:

Steps in Meta for Developers

1. Go to Meta for Developers
2. Select your WhatsApp application
3. Navigate to Products > WhatsApp > Configuration
4. In the Webhooks section, configure:

🛠️ Local Development with ngrok

To test the webhook in your local environment, use ngrok:

1. Download and Install ngrok

Download ngrok from ngrok.com

2. Start Local Server

php artisan serve

3. Expose Server with ngrok

# Option 1: Simple
ngrok http 8000

# Option 2: With host header rewrite (recommended)
ngrok http --host-header=rewrite 8000

4. Use the ngrok URL

ngrok will provide you with a URL like:

https://xxxxxx.ngrok.io

Use this URL in Meta as your webhook:

https://xxxxxx.ngrok.io/whatsapp-webhook

🔍 Final Validation

After completing the installation, verify:

• [ ] Webhook routes are published and accessible
• [ ] Verify token matches in .env and Meta
• [ ] Media directories have write permissions
• [ ] Storage symbolic link works correctly
• [ ] Selected events in Meta cover your needs
• [ ] Logging channel is configured

Quick Test

Send a test message to your WhatsApp Business number and verify it appears in the logs:

tail -f storage/logs/whatsapp.log

🚨 Troubleshooting

Error: "Route not found"

Make sure you've published the routes:

php artisan vendor:publish --tag=whatsapp-routes
php artisan route:list | grep whatsapp

Error: "Directory not writable"

Check storage folder permissions:

chmod -R 775 storage/app/public/whatsapp

Webhook not receiving messages

1. Verify the webhook is correctly configured in Meta
2. Check the logs: storage/logs/whatsapp.log
3. Verify the URL is publicly accessible
4. Confirm the verify token is correct

📚 Next Steps

Once installation is complete, continue with:

• API Configuration - Configure your Meta credentials
• Sending Messages - Start sending messages
• Webhook - Learn about webhook handling

Need help? Check our GitHub or open an issue.