Laravel Evolution API

A production-ready Laravel package for seamless integration with Evolution API - the powerful WhatsApp messaging solution.

Unofficial WhatsApp Integration

This package uses Evolution API, which connects to WhatsApp through the unofficial Baileys library. This is not the official WhatsApp Business API.

Potential Consequences:

• Terms of Service - May violate WhatsApp's ToS
• Account Ban - Your number could be temporarily or permanently banned
• Service Disruption - WhatsApp can block unofficial methods at any time
• No Official Support - Meta/WhatsApp does not support this method

Recommendations:

• Use a dedicated phone number (never your personal number)
• Start with low message volumes and scale gradually
• Avoid spammy behavior - no bulk unsolicited messages
• Have a backup communication channel
• Consider the official WhatsApp Business Platform for critical applications

By using this package, you acknowledge these risks and accept full responsibility.

---

Why Laravel Evolution API?

This package provides everything you need to integrate WhatsApp messaging into your Laravel application with a clean, fluent API.

• Full API Coverage

  ---

  Instance management, messaging, groups, profiles, webhooks, and settings - all through a clean Laravel interface.

  Services

• Rich Message Types

  ---

  Send text, images, videos, audio, documents, locations, contacts, polls, lists, buttons, and reactions.

  Messaging

• Queue Support

  ---

  Send messages asynchronously with Laravel's queue system for better performance and reliability.

  Queues

• Webhook Processing

  ---

  Built-in webhook controller with signature verification and extensible event handlers.

  Webhooks

• Rate Limiting

  ---

  Configurable rate limits to respect API constraints and prevent throttling.

  Rate Limiting

• Metrics & Logging

  ---

  Track message counts, API calls, and errors with multiple driver support.

  Metrics

• Database Models

  ---

  Eloquent models for instances, messages, contacts, and webhook logs with automatic tracking.

  Database

• Testing Utilities

  ---

  Fake implementation with fluent assertions for unit testing your application.

  Testing

---

Quick Installation

composer require lynkbyte/laravel-evolution-api
php artisan evolution-api:install

Add your Evolution API credentials to .env:

EVOLUTION_API_BASE_URL=https://your-evolution-api-server.com
EVOLUTION_API_KEY=your-api-key
EVOLUTION_API_WEBHOOK_SECRET=your-webhook-secret

Full Installation Guide

---

Quick Example

Send a Text Message

use Lynkbyte\EvolutionApi\Facades\EvolutionApi;

// Send a simple text message
$response = EvolutionApi::message()->sendText('my-instance', [
    'number' => '5511999999999',
    'text' => 'Hello from Laravel!',
]);

// Check if it was successful
if ($response->successful()) {
    $messageId = $response->json('key.id');
}

Send a Media Message

// Send an image with caption
$response = EvolutionApi::message()->sendMedia('my-instance', [
    'number' => '5511999999999',
    'mediatype' => 'image',
    'media' => 'https://example.com/image.jpg',
    'caption' => 'Check out this image!',
]);

Handle Webhooks

use Lynkbyte\EvolutionApi\Webhooks\AbstractWebhookHandler;
use Lynkbyte\EvolutionApi\DTOs\WebhookPayloadDto;

class MessageReceivedHandler extends AbstractWebhookHandler
{
    public function handle(WebhookPayloadDto $payload): void
    {
        $message = $payload->data['message'] ?? [];

        // Process the incoming message
        logger()->info('Message received', [
            'from' => $payload->sender,
            'text' => $message['conversation'] ?? null,
        ]);
    }
}

Quick Start Guide

---

Requirements

Requirement	Version
PHP	8.2+
Laravel	11.x / 12.x
Evolution API	2.x

---

Architecture Overview

graph TB
    subgraph Laravel Application
        A[Your Code] --> B[EvolutionApi Facade]
        B --> C[EvolutionService]
        C --> D[Resource Classes]
        D --> E[EvolutionClient]
    end

    subgraph HTTP Layer
        E --> F[Rate Limiter]
        F --> G[HTTP Client]
    end

    subgraph Evolution API
        G <--> H[Evolution API Server]
        H <--> I[WhatsApp]
    end

    subgraph Webhooks
        H --> J[Webhook Controller]
        J --> K[WebhookProcessor]
        K --> L[Event Handlers]
    end

Architecture Details

---

Support

• GitHub

  ---

  Report issues, request features, or contribute to the project.

  GitHub Repository

• Packagist

  ---

  View package details and version history.

  Packagist

---

License

Laravel Evolution API is open-sourced software licensed under the MIT license.

Made with :heart: by Lynkbyte