WhatsApp Manager
🇪🇸 Español 🇬🇧 English

🚀 Getting Started

⚙️ Configuration

💬 Message Management

📋 Templates

📡 Real-time Events

🔧 Advanced

Documentation Documentation

Quick Start

Comprehensive guide for WhatsApp API Manager.

Quick Start

Send your first WhatsApp message in less than 5 minutes.

Prerequisites

Make sure you've completed the package installation.

1. Configure Credentials

Get your credentials from the Meta for Developers console:

# .env
WHATSAPP_API_URL=https://graph.facebook.com
WHATSAPP_API_VERSION=v21.0
WHATSAPP_VERIFY_TOKEN=your-verify-token

2. Register a WhatsApp Number

  • Register a business account in WhatsApp Business API.
    Register and sync WhatsApp Business accounts with their associated phone numbers.
    • The request is made to the WhatsApp API, account data is retrieved and stored in the database. This method gets account data, WhatsApp phones associated with the account, and the profile of each phone number.
    • Used to get data from the API and store it in the database.

⚠️Observations:

  • Requires a valid access token with whatsapp_business_management permissions.
  • The business_id must be the numeric ID of your WhatsApp Business account.
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;

// When registering an account, configured webhooks are automatically subscribed
$account = Whatsapp::account()->register([
    'api_token' => '***********************',
    'business_id' => '1243432234423'
]);

// During registration also:
// - Automatically register all associated phone numbers
// - Subscribe default configured webhooks
// - Configure business profiles

3. Send Your First Message

Simple Text Message

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

$response = Whatsapp::message()->sendTextMessage(
    $phone->phone_number_id, // Phone number ID
    '57',                        // Country code
    '3237121901',                // Phone number
    'Hello, this is a test message.' // Message content
);

Message with Image

Send messages with Images

⚠️ Warning: Make sure the image you send meets WhatsApp requirements:

  • Supported format: JPEG, PNG
  • Maximum recommended size: 5 MB
  • Recommended dimensions: at least 640x640 px
    If the image doesn't meet these requirements, sending may fail.
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

$filePath = storage_path('app/public/laravel-whatsapp-manager.png');
$file = new \SplFileInfo($filePath);

$message = Whatsapp::message()->sendImageMessage(
    $phone->phone_number_id, // Phone number ID
    '57',                        // Country code
    '3237121901',                // Phone number
    $file                       // Image file.
);

Message with Buttons

Send messages with interactive buttons:

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

//EXAMPLE 1
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('Do you confirm your appointment for tomorrow at 3 PM?')
    ->addButton('confirm', '✅ Confirm')
    ->addButton('reschedule', '🔄 Reschedule')
    ->withFooter('Please select an option')
    ->send();

//EXAMPLE 2
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('How would you rate our service?')
    ->addButton('excellent', '⭐️⭐️⭐️⭐️⭐️ Excellent')
    ->addButton('good', '⭐️⭐️⭐️⭐️ Good')
    ->addButton('regular', '⭐️⭐️⭐️ Regular')
    ->withFooter('Your feedback helps us improve')
    ->send();

//EXAMPLE 3
// Get ID from a previous message (you must have a real one)
$contextMessage = \ScriptDevelop\WhatsappManager\Models\Message::first();
$contextId = $contextMessage->wa_id;

$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withBody('Select the type of support you need:')
    ->addButton('technical-support', '🛠️ Technical Support')
    ->addButton('billing', '🧾 Billing')
    ->addButton('complaints', '📣 Complaints')
    ->withFooter('Office hours: M-F 8am-6pm')
    ->inReplyTo($contextId)  // Here you specify the message you're replying to
    ->send();

// EXAMPLES WITH text HEADER
$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withHeader('Digital Catalog')
    ->withBody('Do you confirm your appointment for tomorrow at 3 PM?')
    ->addButton('confirm', '✅ Confirm')
    ->addButton('reschedule', '🔄 Reschedule')
    ->withFooter('Please select an option')
    ->send();

// EXAMPLES WITH image HEADER
$file = new \SplFileInfo(storage_path('app/public/laravel-whatsapp-manager.png'));

$buttonResponse = Whatsapp::sendButtonMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withHeader($file)
    ->withBody('Do you confirm your appointment for tomorrow at 3 PM?')
    ->addButton('confirm', '✅ Confirm')
    ->addButton('reschedule', '🔄 Reschedule')
    ->withFooter('Please select an option')
    ->send();

4. Receive Messages

Configure Webhook

First, configure your webhook in Meta for Developers following the installation guide.

Listen to Events

Create a listener for incoming messages:

// app/Listeners/HandleIncomingMessage.php
namespace App\Listeners;

use ScriptDevelop\WhatsappManager\Events\TextMessageReceived;
use Illuminate\Contracts\Queue\ShouldQueue;

class HandleIncomingMessage implements ShouldQueue
{
    public function handle(TextMessageReceived $event)
    {
        $message = $event->message;
        $contact = $event->contact;

        logger()->info("Message from {$contact->name}: {$message->body}");

        // Your logic here
        // For example, auto-reply:
        Whatsapp::sendTextMessage(
            phoneId: $message->whatsapp_phone_id,
            to: $contact->whatsapp_id,
            message: "Hello {$contact->name}! We received your message: '{$message->body}'"
        );
    }
}

Register the listener in app/Providers/EventServiceProvider.php:

use ScriptDevelop\WhatsappManager\Events\TextMessageReceived;
use App\Listeners\HandleIncomingMessage;

protected $listen = [
    TextMessageReceived::class => [
        HandleIncomingMessage::class,
    ],
];

5. Working with Templates

Templates are pre-approved messages by WhatsApp that you can send to any user:

// Send template
use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

// Send template 1: template without buttons or without needing to provide button parameters
$message = Whatsapp::template()
    ->sendTemplateMessage($phone)
    ->to('57', '3137555908')
    ->usingTemplate('order_confirmation_4')
    ->addBody(['12345'])
    ->send();

Complete Examples

Response System with Lists

use ScriptDevelop\WhatsappManager\Facades\Whatsapp;
use ScriptDevelop\WhatsappManager\Models\WhatsappBusinessAccount;

$account = WhatsappBusinessAccount::first();
$phone = $account->phoneNumbers->first();

// EXAMPLE 1 - WITHOUT CHAINING
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('View Products')
    ->withBody('Our featured products:')
    ->withHeader('Digital Catalog')
    ->withFooter('Swipe to see more options');

$listBuilder->startSection('Laptops')
    ->addRow('laptop-pro', 'MacBook Pro', '16" - 32GB RAM - 1TB SSD')
    ->addRow('laptop-air', 'MacBook Air', '13" - M2 Chip - 8GB RAM')
    ->endSection();

$listBuilder->startSection('Smartphones')
    ->addRow('iphone-15', 'iPhone 15 Pro', '48MP Camera - 5G')
    ->addRow('samsung-s23', 'Samsung S23', 'AMOLED Screen 120Hz')
    ->endSection();

$response = $listBuilder->send();

// EXAMPLE 2 - CHAINED
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('View Services')
    ->withBody('Select the service you want to schedule:')
    ->withFooter('Swipe to see all options')
    ->startSection('Haircuts')
        ->addRow('women-cut', 'Women Haircut', 'Professional style')
        ->addRow('men-cut', 'Men Haircut', 'Modern techniques')
        ->addRow('kids-cut', 'Kids Haircut', 'Children designs')
    ->endSection()
    ->startSection('Treatments')
        ->addRow('keratin', 'Keratin', 'Repairing treatment')
        ->addRow('coloring', 'Coloring', 'Professional dyes')
        ->addRow('mask', 'Mask', 'Deep hydration')
    ->endSection();

$response = $listBuilder->send();

// EXAMPLE 3 - reply to messages
// Get ID from a previous message (you must have a real one)
$contextMessage = \ScriptDevelop\WhatsappManager\Models\Message::first();
$contextId = $contextMessage->wa_id;

$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '31371235638')
    ->withButtonText('Select Service')
    ->withBody('For the type of appointment you mentioned, we have these options:')
    ->inReplyTo($contextId); // Here you specify the message you're replying to

$listBuilder->startSection('Consultations')
    ->addRow('general-consultation', 'General Consultation', '30 min - $50.000')
    ->addRow('special-consultation', 'Specialized Consultation', '60 min - $90.000')
    ->endSection();

$listBuilder->startSection('Treatments')
    ->addRow('basic-treatment', 'Basic Treatment', 'Individual session')
    ->addRow('premium-treatment', 'Premium Treatment', 'Includes follow-up')
    ->endSection();

$response = $listBuilder->send();

// EXAMPLE WITH text HEADER
$listBuilder = Whatsapp::sendListMessage($phone->phone_number_id)
    ->to('57', '313714R3534')
    ->withButtonText('View Products')
    ->withHeader('Digital Catalog') // TEXT HEADER
    ->withBody('Our featured products:')
    ->withFooter('Swipe to see more options')
    ->startSection('Laptops')
        ->addRow('laptop-pro', 'MacBook Pro', '16" - 32GB RAM - 1TB SSD')
        ->addRow('laptop-air', 'MacBook Air', '13" - M2 Chip - 8GB RAM')
    ->endSection()
    ->startSection('Smartphones')
        ->addRow('iphone-15', 'iPhone 15 Pro', '48MP Camera - 5G')
        ->addRow('samsung-s23', 'Samsung S23', 'AMOLED Screen 120Hz')
    ->endSection()
    ->send();

Check Message Status

All sent messages are saved in the database:

use ScriptDevelop\WhatsappManager\Models\WhatsappMessage;

$message = WhatsappMessage::where('wa_id', 'wamid.xxxxx')->first();

echo "Status: {$message->status}\n";
echo "Sent to: {$message->message_to}\n";
echo "Type: {$message->message_type}\n";

Logs and Debugging

All events are logged in storage/logs/whatsapp.log:

# View logs in real-time
tail -f storage/logs/whatsapp.log

Next Steps

Congratulations! You've sent your first message. Now you can:

Troubleshooting

Error: "Invalid Phone Number"

Make sure to include the country code without the + sign:

// ❌ Incorrect
to: '+5491234567890'

// ✅ Correct
to: '5491234567890'

Error: "Invalid Access Token"

Verify that the token is active and has the necessary permissions in Meta for Developers.

Not receiving messages

  1. Verify the webhook is correctly configured
  2. Check the logs: storage/logs/whatsapp.log
  3. Confirm events are subscribed in Meta

Need more help? Open an issue on GitHub.

Share this page

Edit this page on GitHub