README

A Laravel client for the Evolution API, providing simple integration with WhatsApp for messaging, group management, and more.

Features

Complete WhatsApp functionality through Evolution API
Send and receive messages (text, media, buttons, lists, polls)
Create and manage groups
Manage contacts and labels
Handle webhook events
Simple and clean Laravel integration

Installation

You can install the package via composer:

composer require vitorfba/laravel-evolution-client

You can publish the configuration file with:

php artisan vendor:publish --tag="evolution-config"

This is the content of the published configuration file:

return [
    /*
    |--------------------------------------------------------------------------
    | Evolution API Base URL
    |--------------------------------------------------------------------------
    |
    | This is the base URL for the Evolution API endpoints. This should be
    | the URL of your Evolution API server.
    |
    */
    'base_url' => env('EVOLUTION_API_URL', 'http://localhost:8080'),

    /*
    |--------------------------------------------------------------------------
    | Evolution API Key
    |--------------------------------------------------------------------------
    |
    | This is your API key which is used to authenticate with the Evolution API.
    | You can get this from your Evolution API configuration.
    |
    */
    'api_key' => env('EVOLUTION_API_KEY', ''),

    /*
    |--------------------------------------------------------------------------
    | Default Instance Name
    |--------------------------------------------------------------------------
    |
    | The default instance name to use when none is provided.
    |
    */
    'default_instance' => env('EVOLUTION_DEFAULT_INSTANCE', 'default'),

    /*
    |--------------------------------------------------------------------------
    | Request Timeout
    |--------------------------------------------------------------------------
    |
    | This value determines the maximum number of seconds to wait for a response
    | from the Evolution API server.
    |
    */
    'timeout' => env('EVOLUTION_API_TIMEOUT', 30),

    /*
    |--------------------------------------------------------------------------
    | Webhook URL
    |--------------------------------------------------------------------------
    |
    | The URL where Evolution API will send webhook events.
    |
    */
    'webhook_url' => env('EVOLUTION_WEBHOOK_URL', null),

    /*
    |--------------------------------------------------------------------------
    | Webhook Events
    |--------------------------------------------------------------------------
    |
    | The events that should trigger the webhook.
    |
    */
    'webhook_events' => [
        'message',
        'message.ack',
        'status.instance',
        // Add more events as needed
    ],
];

Usage

Configuring the .env

EVOLUTION_API_URL=http://your-evolution-api.com
EVOLUTION_API_KEY=your-api-key
EVOLUTION_DEFAULT_INSTANCE=default

Using the Facade

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// Check QR Code
$qrCode = Evolution::getQrCode();

// Check if connected
$connected = Evolution::isConnected();

// Send text message
$result = Evolution::sendText('5511999999999', 'Hello, this is a test message!');

Using Different Instances

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// Use a specific instance
$result = Evolution::instance('my-instance')->sendText('5511999999999', 'Hello!');

Working with Chats

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// List/filter chats (POST /chat/findChats)
$chats = Evolution::chat->findChats();

// Filter messages (POST /chat/findMessages)
$messages = Evolution::chat->findMessages([
    'where' => ['key' => ['remoteJid' => '5511999999999@s.whatsapp.net']],
]);

// Filter contacts (POST /chat/findContacts)
$contacts = Evolution::chat->findContacts();

// Delete a message for everyone (DELETE /chat/deleteMessageForEveryone)
Evolution::chat->deleteMessageForEveryone('MESSAGE_ID', '5511999999999@s.whatsapp.net', true);

// Mark messages as read
Evolution::chat->markAsRead([
    ['remoteJid' => '5511999999999@s.whatsapp.net', 'fromMe' => false, 'id' => 'MESSAGE_ID'],
]);

Working with Groups

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// List all groups
$groups = Evolution::group->all();

// Create a new group
$newGroup = Evolution::group->create('Group Name', [
    '5511999999999',
    '5511888888888',
]);

// Add participants to a group
Evolution::group->addParticipants($groupId, [
    '5511777777777',
]);

// Promote to admin
Evolution::group->promoteToAdmin($groupId, '5511999999999');

Sending Different Types of Messages

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;
use Vitorfba\LaravelEvolutionClient\Models\Button;
use Vitorfba\LaravelEvolutionClient\Models\ListRow;
use Vitorfba\LaravelEvolutionClient\Models\ListSection;

// Send text
Evolution::message->sendText('5511999999999', 'Hello, how are you?');

// Group ids may be passed bare or with their existing @g.us suffix
Evolution::message->sendText('123456789@g.us', 'Hello, group!', true);

// Send text with delay and link preview
Evolution::message->sendText('5511999999999', 'Check out this website: https://example.com', false, 1000, true);

// Send image
Evolution::message->sendImage('5511999999999', 'https://example.com/image.jpg', 'Image caption');

// Send document
Evolution::message->sendDocument('5511999999999', 'https://example.com/document.pdf', 'filename.pdf', 'Check out this document');

// Send location
Evolution::message->sendLocation('5511999999999', -23.5505, -46.6333, 'São Paulo', 'Paulista Avenue, 1000');

// Send contact
Evolution::message->sendContact('5511999999999', 'Contact Name', '5511888888888');

// Send poll
Evolution::message->sendPoll('5511999999999', 'What is your favorite color?', 1, ['Blue', 'Green', 'Red', 'Yellow']);

// Send list
$rows1 = [
    new ListRow('Option 1', 'Description of option 1', 'opt1'),
    new ListRow('Option 2', 'Description of option 2', 'opt2')
];
$rows2 = [
    new ListRow('Option 3', 'Description of option 3', 'opt3'),
    new ListRow('Option 4', 'Description of option 4', 'opt4')
];

$sections = [
    new ListSection('Section 1', $rows1),
    new ListSection('Section 2', $rows2)
];

Evolution::message->sendList(
    '5511999999999',
    'List Title',
    'Choose an option',
    'View Options',
    'List footer',
    $sections
);

// Send buttons
$buttons = [
    new Button('reply', 'Yes', ['id' => 'btn-yes']),
    new Button('reply', 'No', ['id' => 'btn-no']),
    new Button('url', 'Visit Website', ['url' => 'https://example.com'])
];

Evolution::message->sendButtons(
    '5511999999999',
    'Confirmation',
    'Do you want to proceed with the operation?',
    'Choose an option below',
    $buttons
);

// Send reaction to a message
Evolution::message->sendReaction(
    ['remoteJid' => '5511999999999@c.us', 'id' => 'ABCDEF123456', 'fromMe' => false],
    '👍'
);

// Send status
Evolution::message->sendStatus(
    'text',
    'Hello, this is my status!',
    null,
    '#25D366',
    2,
    true
);

Working with Labels

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// List all labels
$labels = Evolution::label->findLabels();

// Add a label to a chat
Evolution::label->addLabel('5511999999999', 'label_id_123');

// Remove a label from a chat
Evolution::label->removeLabel('5511999999999', 'label_id_123');

Working with Calls

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// Make a fake call
Evolution::call->fakeCall('5511999999999', false, 45); // Voice call with 45 seconds
Evolution::call->fakeCall('5511999999999', true, 30);  // Video call with 30 seconds

Working with Profile

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// Fetch a contact's profile
$profile = Evolution::profile->fetchProfile('5511999999999');

// Fetch business profile
$businessProfile = Evolution::profile->fetchBusinessProfile('5511999999999');

// Update profile name
Evolution::profile->updateProfileName('My Name');

// Update status
Evolution::profile->updateProfileStatus('Available for service');

// Update profile picture
Evolution::profile->updateProfilePicture('data:image/jpeg;base64,/9j/4AAQSkZJRgABAQE...');

// Remove profile picture
Evolution::profile->removeProfilePicture();

// Fetch privacy settings
$privacySettings = Evolution::profile->fetchPrivacySettings();

// Update privacy settings
Evolution::profile->updatePrivacySettings(
    'all',               // readreceipts
    'contacts',          // profile
    'contacts',          // status
    'all',               // online
    'contacts',          // last
    'contacts'           // groupadd
);

Working with WebSocket

use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

// Configure WebSocket
Evolution::websocket->setWebSocket(true, [
    'message',
    'message.ack',
    'status.instance'
]);

// Fetch WebSocket configuration
$webSocketConfig = Evolution::websocket->findWebSocket();

// Create a WebSocket client
$webSocketClient = Evolution::websocket->createClient();

// Register handlers for events
$webSocketClient->on('message', function ($data) {
    // Process received message
    Log::info('New message received', $data);
});

$webSocketClient->on('message.ack', function ($data) {
    // Process read confirmation
    Log::info('Message read', $data);
});

// Connect to WebSocket server
$webSocketClient->connect();

// ... At some later point, disconnect
$webSocketClient->disconnect();

Working with Templates

// Create a template
$response = Evolution::template->create(
    'my_template',
    'MARKETING',
    'en_US',
    [
        [
            'type' => 'BODY',
            'text' => 'Hello {{1}}, welcome to our service!',
            'example' => [
                'body_text' => [
                    ['John Doe']
                ]
            ]
        ],
        [
            'type' => 'BUTTONS',
            'buttons' => [
                [
                    'type' => 'QUICK_REPLY',
                    'text' => 'Yes, please'
                ],
                [
                    'type' => 'QUICK_REPLY',
                    'text' => 'No, thanks'
                ]
            ]
        ]
    ]
);

// Find templates
$templates = Evolution::template->find();

// Send a template message
Evolution::message->sendTemplate(
    '5511999999999',
    'my_template',
    'en_US',
    [
        [
            'type' => 'body',
            'parameters' => [
                [
                    'type' => 'text',
                    'text' => 'John Doe'
                ]
            ]
        ]
    ]
);

Managing Settings

// Set instance settings
Evolution::settings->set(
    true,  // reject calls
    'I cannot take calls right now', // call message
    false, // don't ignore groups
    true,  // always show online
    false, // don't read messages automatically
    false, // don't sync full history
    false  // don't read status automatically
);

// Get current settings
$settings = Evolution::settings->find();

Evolution Bot

// Create evolution bot
Evolution::evolutionBot->create(
    enabled: true,
    apiUrl: 'https://api.mybot.com/webhook',
    apiKey: 'your-secret-api-key-for-the-bot',
    triggerType: 'keyword',
    triggerOperator: 'equals',
    triggerValue: '!menu',
    expire: 300,
    keywordFinish: '!exit',
    delayMessage: 1200,
    unknownMessage: 'Sorry.',
    listeningFromMe: false,
    stopBotFromMe: true,
    keepOpen: false,
    debounceTime: 1000
);

// Delete evolution bot
$settings = Evolution::evolutionBot->destroy($evolutionBotId);

Using Proxy

// Set proxy
Evolution::proxy->set(
    true,     // enabled
    '127.0.0.1', // host
    '8080',   // port
    'http',   // protocol
    'username', // optional
    'password'  // optional
);

// Get current proxy settings
$proxy = Evolution::proxy->find();

Handling Webhooks

Evolution API delivers events (incoming messages, connection changes, QR updates, …) to a URL you configure. This package parses those payloads into a typed WebhookEvent and exposes them for use.

1. Register the endpoint. Enable the built-in route in config/evolution.php:

'webhook' => [
    'route' => [
        'enabled'    => env('EVOLUTION_WEBHOOK_ROUTE_ENABLED', true),
        'path'       => env('EVOLUTION_WEBHOOK_ROUTE_PATH', 'evolution/webhook'),
        'middleware' => ['api'],
    ],
],

Point your instance webhook at https://your-app.test/evolution/webhook. (Or build your own controller and call WebhookProcessor::process($request) yourself.)

2. Listen for events. Every webhook dispatches EvolutionWebhookReceived, plus a named evolution.webhook.{event} event:

use Vitorfba\LaravelEvolutionClient\Events\EvolutionWebhookReceived;
use Vitorfba\LaravelEvolutionClient\Webhook\WebhookEvent;

Event::listen(function (EvolutionWebhookReceived $received) {
    $event = $received->webhook;                 // WebhookEvent

    if ($event->isMessageUpsert()) {
        $from = $event->get('key.remoteJid');
        $text = $event->get('message.conversation');
        // ...
    }
});

Make your listener implement ShouldQueue to process it on a queue.

3. (Optional) Queue at the edge. To return 200 to Evolution instantly and process off the request lifecycle, enable the queue — a ProcessEvolutionWebhook job is dispatched instead of running inline:

'webhook' => [
    'queue' => ['enabled' => env('EVOLUTION_WEBHOOK_QUEUE_ENABLED', true)],
],

You can also register inline callbacks without Laravel events:

app(\Vitorfba\LaravelEvolutionClient\Webhook\WebhookProcessor::class)
    ->on(WebhookEvent::MESSAGES_UPSERT, fn (WebhookEvent $e) => logger($e->toArray()))
    ->onAny(fn (WebhookEvent $e) => logger("event: {$e->name()}"));

Testing

composer test        # Pest test suite
composer lint        # Laravel Pint (code style, dry-run)
composer analyse     # Larastan level 5 (static analysis)
composer format      # apply Pint fixes

Changelog

Please see the CHANGELOG for more information about what has changed recently.

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security-related issues, please open an issue on GitHub instead of using the issue tracker for sensitive reports, or contact the maintainer privately.

Credits

License

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

vitorfba / laravel-evolution-client

Maintainers

Package info

Fund package maintenance!

Statistics

Security

README

Features

Installation

Usage

Configuring the .env

Using the Facade

Using Different Instances

Working with Chats

Working with Groups

Sending Different Types of Messages

Working with Labels

Working with Calls

Working with Profile

Working with WebSocket

Handling Webhooks

Testing

Changelog

Contributing

Security

Credits

License