PHPackages                             vitorfba/laravel-evolution-client - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. vitorfba/laravel-evolution-client

ActiveLibrary[API Development](/categories/api)

vitorfba/laravel-evolution-client
=================================

Laravel Client for Evolution API, allowing easy integration with WhatsApp.

v1.2.0(yesterday)08↑2900%MITPHPPHP ^8.2

Since Jul 23Pushed yesterdayCompare

[ Source](https://github.com/vitorfba/laravel-evolution-client)[ Packagist](https://packagist.org/packages/vitorfba/laravel-evolution-client)[ Docs](https://github.com/vitorfba/laravel-evolution-client)[ GitHub Sponsors](https://github.com/vitorfba)[ RSS](/packages/vitorfba-laravel-evolution-client/feed)WikiDiscussions main Synced today

READMEChangelogDependencies (14)Versions (4)Used By (0)

Laravel Evolution Client
========================

[](#laravel-evolution-client)

[![Latest Version on Packagist](https://camo.githubusercontent.com/e3ab78401b14c11d440d6cafd1ea8ad8bebab71b0724b1585bc0cf44ab28b5eb/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f7669746f726662612f6c61726176656c2d65766f6c7574696f6e2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/vitorfba/laravel-evolution-client)[![run-tests](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/run-tests.yml/badge.svg?branch=main)](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/run-tests.yml)[![Fix PHP code style issues](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/fix-php-code-style-issues.yml/badge.svg?branch=main)](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/fix-php-code-style-issues.yml)[![PHPStan](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/phpstan.yml/badge.svg?branch=main)](https://github.com/vitorfba/laravel-evolution-client/actions/workflows/phpstan.yml)[![Total Downloads](https://camo.githubusercontent.com/dd8439c2bfecaf35d8cad20a8d7a89d89c13504a51c94078380322a940b92bd2/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f7669746f726662612f6c61726176656c2d65766f6c7574696f6e2d636c69656e742e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/vitorfba/laravel-evolution-client)

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

Features
--------

[](#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
------------

[](#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
-----

[](#usage)

### Configuring the .env

[](#configuring-the-env)

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

```

### Using the Facade

[](#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

[](#using-different-instances)

```
use Vitorfba\LaravelEvolutionClient\Facades\Evolution;

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

### Working with Chats

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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

[](#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
-------

[](#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
---------

[](#changelog)

Please see the [CHANGELOG](CHANGELOG.md) for more information about what has changed recently.

Contributing
------------

[](#contributing)

Please see [CONTRIBUTING](CONTRIBUTING.md) for details.

Security
--------

[](#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
-------

[](#credits)

- [Vitor](https://github.com/vitorfba)
- [All Contributors](../../contributors)

License
-------

[](#license)

The MIT License (MIT). Please see the [License File](LICENSE.md) for more information.

###  Health Score

43

—

FairBetter than 89% of packages

Maintenance100

Actively maintained with recent releases

Popularity7

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity48

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 70.8% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

1d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/6035167?v=4)[Vitor Fernandes](/maintainers/vitorfba)[@vitorfba](https://github.com/vitorfba)

---

Top Contributors

[![samuelterra22](https://avatars.githubusercontent.com/u/11915449?v=4)](https://github.com/samuelterra22 "samuelterra22 (51 commits)")[![happones](https://avatars.githubusercontent.com/u/11873340?v=4)](https://github.com/happones "happones (10 commits)")[![vitorfba](https://avatars.githubusercontent.com/u/6035167?v=4)](https://github.com/vitorfba "vitorfba (8 commits)")[![stvieira](https://avatars.githubusercontent.com/u/148778229?v=4)](https://github.com/stvieira "stvieira (3 commits)")

---

Tags

apilaravelwhatsappevolution-apievolution

###  Code Quality

TestsPest

Static AnalysisPHPStan

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/vitorfba-laravel-evolution-client/health.svg)

```
[![Health](https://phpackages.com/badges/vitorfba-laravel-evolution-client/health.svg)](https://phpackages.com/packages/vitorfba-laravel-evolution-client)
```

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3345.3M347](/packages/psalm-plugin-laravel)[simplestats-io/laravel-client

Server-side analytics for Laravel that follows the full funnel from visit to registration to payment, attributed to the channel that drove it. Revenue, MRR, churn and ad-spend profit (ROAS/CAC) per channel. GDPR compliant, ad-blocker proof.

5022.6k](/packages/simplestats-io-laravel-client)[defstudio/telegraph

A laravel facade to interact with Telegram Bots

813336.8k3](/packages/defstudio-telegraph)[api-platform/laravel

API Platform support for Laravel

58174.6k17](/packages/api-platform-laravel)[eslazarev/wildberries-sdk

Wildberries OpenAPI clients (generated).

293.1k](/packages/eslazarev-wildberries-sdk)[telnyx/telnyx-php

Official Telnyx PHP SDK — APIs for Voice, SMS, MMS, WhatsApp, Fax, SIP Trunking, Wireless IoT, Call Control, and more. Build global communications on Telnyx's private carrier-grade network.

35789.4k2](/packages/telnyx-telnyx-php)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)