README

Framework-independent PHP SDK for the Evolution GO HTTP API.

This documentation is aligned with the local Swagger contract at /media/ex/evolution-go/docs/swagger.json reviewed on 2026-08-08. The public SDK resources cover the Evolution GO API groups, including interactive messages (button, list, carousel), statuses, chats, groups, users, labels, newsletters, communities, calls, polls, license, and passkey ceremony endpoints.

Portuguese documentation is available in README.pt.md.

Installation

During local development this package is usually consumed by the main Laravel application through Composer path repositories.

composer require gabrielmoura/evolutiongo-sdk

For package development, install dev dependencies from this directory:

composer install
composer test

Client

use GabrielMoura\EvolutionGo\EvolutionGo;
use GabrielMoura\EvolutionGo\EvolutionGoConnection;

$client = new EvolutionGo(EvolutionGoConnection::fromCredential([
    'base_url' => 'http://localhost:8080',
    'api_key' => 'instance-or-global-api-key',
]));

EvolutionGoConnection::fromCredential() accepts:

• base_url or url
• api_key, apikey, or token

Authentication is sent through the HTTP apikey header. Tenant resolution, credential storage, and channel/instance selection are application responsibilities.

Responses and Errors

Some endpoints already return typed DTOs:

• instances()->status()
• instances()->all()
• instances()->info($instanceId)
• instances()->qr()
• groups()->list()
• users()->contacts()
• messages()->sendText(...)

The remaining endpoints return GabrielMoura\EvolutionGo\Responses\EvolutionGoResponse, preserving Saloon response behavior:

$response = $client->messages()->sendButton([...]);

$response->throw();
$message = $response->json('message');
$data = $response->json('data');

All SDK exceptions extend GabrielMoura\EvolutionGo\Exceptions\EvolutionGoException. Failed API responses throw EvolutionGoRequestException or a more specific subclass:

EvolutionGoRequestException exposes statusCode(), responseBody, apiError(), and details(). The exception message is derived from the API error field when available and never includes the API key or base URL.

use GabrielMoura\EvolutionGo\Exceptions\EvolutionGoAuthenticationException;
use GabrielMoura\EvolutionGo\Exceptions\EvolutionGoRequestException;
use GabrielMoura\EvolutionGo\Exceptions\EvolutionGoValidationException;

try {
    $client->messages()->sendButton([...])->throw();
} catch (EvolutionGoValidationException $exception) {
    report($exception->apiError());
    $details = $exception->details();
} catch (EvolutionGoAuthenticationException) {
    // Refresh or disable the stored credential.
} catch (EvolutionGoRequestException $exception) {
    report($exception);
}

Messages

Text

use GabrielMoura\EvolutionGo\Data\Message\SendTextMessageData;

$message = $client->messages()->sendText(new SendTextMessageData(
    number: '5511999990001',
    text: 'Hello',
    delay: 1000,
));

Arrays are also supported:

$client->messages()->sendText([
    'number' => '5511999990001',
    'text' => 'Hello',
    'mentionedJid' => ['5511888880001@s.whatsapp.net'],
    'mentionAll' => false,
    'formatJid' => true,
    'quoted' => [
        'messageId' => '3EB0...',
        'participant' => '5511888880001@s.whatsapp.net',
    ],
]);

Buttons

sendButton() covers POST /send/button. The API accepts reply, copy, url, call, and pix buttons.

$client->messages()->sendButton([
    'number' => '5511999990001',
    'title' => 'Special offer',
    'description' => 'Review the details below',
    'footer' => 'Evolution GO',
    'imageUrl' => 'https://example.com/header.jpg',
    'buttons' => [
        [
            'type' => 'reply',
            'displayText' => 'Tell me more',
            'id' => 'btn_info',
        ],
        [
            'type' => 'copy',
            'displayText' => 'Copy coupon',
            'copyCode' => 'PROMO2026',
        ],
        [
            'type' => 'url',
            'displayText' => 'Open site',
            'url' => 'https://example.com',
        ],
        [
            'type' => 'call',
            'displayText' => 'Call',
            'phoneNumber' => '+5511999990001',
        ],
        [
            'type' => 'pix',
            'displayText' => 'Pay with PIX',
            'keyType' => 'cpf',
            'key' => '12345678900',
            'name' => 'My Store',
            'currency' => 'BRL',
        ],
    ],
]);

Common message fields may also be sent: delay, mentionedJid, mentionAll, formatJid, and quoted.

List

sendList() covers POST /send/list.

$client->messages()->sendList([
    'number' => '5511999990001',
    'title' => 'Our plans',
    'description' => 'Choose the best plan',
    'buttonText' => 'Open menu',
    'footerText' => 'Evolution GO',
    'sections' => [
        [
            'title' => 'Plans',
            'rows' => [
                [
                    'title' => 'Basic Plan',
                    'description' => 'R$ 29.90/month',
                    'rowId' => 'plan_basic',
                ],
                [
                    'title' => 'Pro Plan',
                    'description' => 'R$ 59.90/month',
                    'rowId' => 'plan_pro',
                ],
            ],
        ],
    ],
]);

Carousel

sendCarousel() covers POST /send/carousel.

$client->messages()->sendCarousel([
    'number' => '5511999990001',
    'body' => 'Check out our latest updates',
    'footer' => 'Evolution GO',
    'cards' => [
        [
            'header' => [
                'title' => 'Deal of the day',
                'subtitle' => 'Today only',
                'imageUrl' => 'https://example.com/card-1.jpg',
            ],
            'body' => [
                'text' => 'Card 1 - Special offer',
            ],
            'footer' => 'Limited time',
            'buttons' => [
                [
                    'type' => 'REPLY',
                    'displayText' => 'Details',
                    'id' => 'card1_info',
                ],
                [
                    'type' => 'URL',
                    'displayText' => 'Open',
                    'url' => 'https://example.com/offer',
                ],
            ],
        ],
    ],
]);

Other Send Endpoints

$client->messages()->sendLink([...]);        // POST /send/link
$client->messages()->sendMedia([...]);       // POST /send/media
$client->messages()->sendPoll([...]);        // POST /send/poll
$client->messages()->sendSticker([...]);     // POST /send/sticker
$client->messages()->sendLocation([...]);    // POST /send/location
$client->messages()->sendContact([...]);     // POST /send/contact
$client->messages()->sendStatusText([...]);  // POST /send/status/text
$client->messages()->sendStatusMedia([...]); // POST /send/status/media

For media status uploads, use the multipart format expected by Saloon when sending a local file. For remote URLs, pass the fields accepted by the API (type, url, caption, id) according to the Evolution GO contract.

Message Operations

$client->messages()->react([...]);         // POST /message/react
$client->messages()->presence([...]);      // POST /message/presence
$client->messages()->markRead([...]);      // POST /message/markread
$client->messages()->markPlayed([...]);    // POST /message/markplayed
$client->messages()->downloadMedia([...]); // POST /message/downloadmedia
$client->messages()->status([...]);        // POST /message/status
$client->messages()->delete([...]);        // POST /message/delete
$client->messages()->edit([...]);          // POST /message/edit

Available Resources

Low-level request classes remain available under GabrielMoura\EvolutionGo\Requests\... for consumers that need to call Saloon directly.

Domain Examples

$client->instances()->status();
$client->instances()->create(['instanceName' => 'main']);
$client->instances()->setProxy('instance-id', ['proxy' => ['enabled' => true]]);

$client->groups()->create([
    'subject' => 'Support',
    'participants' => ['5511999990001'],
]);

$client->users()->check(['number' => '5511999990001']);
$client->labels()->chat(['number' => '5511999990001', 'labelId' => '1']);
$client->polls()->results('poll-message-id');

Compatibility

• PHP: ^8.3
• Saloon: ^4.0
• Pest: ^4.7 for package development
• Evolution GO: local /media/ex/evolution-go/docs/swagger.json contract reviewed on 2026-08-08