PHPackages                             innovation-studios/evolution-api-plugin - 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. innovation-studios/evolution-api-plugin

ActiveLibrary[API Development](/categories/api)

innovation-studios/evolution-api-plugin
=======================================

Plugin PHP para integração com a Evolution API - Suporte completo para versões 1.x e 2.x

v1.0.0(7mo ago)0273MITPHPPHP ^8.1

Since Oct 10Pushed 7mo ago1 watchersCompare

[ Source](https://github.com/innovationstudios/evolution-php)[ Packagist](https://packagist.org/packages/innovation-studios/evolution-api-plugin)[ RSS](/packages/innovation-studios-evolution-api-plugin/feed)WikiDiscussions main Synced 1mo ago

READMEChangelogDependencies (1)Versions (2)Used By (0)

Evolution API Plugin
====================

[](#evolution-api-plugin)

Este plugin facilita a integração com a API Evolution, permitindo criar instâncias, enviar mensagens e muito mais.

Instalação
----------

[](#instalação)

Instale o plugin via Composer:

```
composer require innovation-studios/evolution-api-plugin
```

### Configuração

[](#configuração)

#### Laravel

[](#laravel)

Se estiver usando Laravel, publique o arquivo de configuração:

```
php artisan vendor:publish --tag=config
```

Isso criará o arquivo `config/evolution.php`, onde você pode configurar a URL e a chave da API.

No arquivo `.env`, adicione as seguintes variáveis:

```
EVOLUTION_API_URL=SEU_URL_AQUI
EVOLUTION_API_KEY=SUA_CHAVE_AQUI
```

#### Uso Direto (PHP Puro)

[](#uso-direto-php-puro)

Se não estiver usando Laravel, configure a API diretamente ao instanciar a classe:

```
use EvolutionApiPlugin\EvolutionApi;

$apiKey = 'SUA_CHAVE_AQUI';
$apiUrl = 'SEU_URL_AQUI'; // Opcional, padrão: ''

$evolutionApi = new EvolutionApi($apiKey, $apiUrl);
```

Métodos Disponíveis
-------------------

[](#métodos-disponíveis)

### Criar Instância

[](#criar-instância)

```
$response = $evolutionApi->createInstance(
    'exampleInstance', // Nome da instância
    'SEU_TOKEN_AQUI', // Token
    true // Gerar QR Code
);
```

### Enviar Mensagem de Texto

[](#enviar-mensagem-de-texto)

```
$response = $evolutionApi->sendTextMessage(
    '5511999999999', // Número
    'Olá, mundo!',   // Texto da mensagem
    [                // Opções (opcional)
        'delay' => 2,
        'presence' => 'composing',
    ],
    [                // Menções (opcional)
        'everyone' => false,
        'mentioned' => ['fulano', 'ciclano'],
    ]
);
```

### Envia Mensagem de Imagem

[](#envia-mensagem-de-imagem)

```
$mediaMessage = [
    'mediatype' => 'image',
    'fileName' => 'foto.jpg',
    'caption' => 'Esta é uma imagem de exemplo',
    'media' => 'https://exemplo.com/foto.jpg', // URL ou base64 da mídia
];
$response = $evolutionApi->sendMediaMessage($instanceName, $number, $mediaMessage);
```

### Enviar Lista

[](#enviar-lista)

```
$listMessage = [
    'title' => 'Título da Lista',
    'description' => 'Descrição da Lista',
    'footerText' => 'Texto do Rodapé',
    'buttonText' => 'Texto do Botão',
    'sections' => [
        [
            'title' => 'Seção 1',
            'rows' => [
                [
                    'title' => 'Item 1',
                    'description' => 'Descrição do Item 1',
                    'rowId' => 'item1',
                ],
                [
                    'title' => 'Item 2',
                    'description' => 'Descrição do Item 2',
                    'rowId' => 'item2',
                ],
            ],
        ],
    ],
];

$response = $evolutionApi->sendList($instanceName, $number, $listMessage);
```

### Listar Instância

[](#listar-instância)

```
$response = $evolutionApi->fetchInstance('exampleInstance');
```

### Excluir Instância

[](#excluir-instância)

```
$response = $evolutionApi->deleteInstance('exampleInstance');
```

Exemplos
--------

[](#exemplos)

### Laravel

[](#laravel-1)

```
use EvolutionApiPlugin\EvolutionApi;

class ExampleController extends Controller
{
    protected $evolutionApi;

    public function __construct(EvolutionApi $evolutionApi)
    {
        $this->evolutionApi = $evolutionApi;
    }

    public function sendMessage()
    {
        $response = $this->evolutionApi->sendTextMessage(
            '5511999999999', // Número
            'Olá, mundo!'    // Texto da mensagem
        );

        return response()->json($response);
    }
}
```

### PHP Puro

[](#php-puro)

```
use EvolutionApiPlugin\EvolutionApi;

$apiKey = 'SUA_CHAVE_AQUI';
## Evolution API Plugin

Biblioteca PHP para integrar aplicações (Laravel ou PHP puro) com a API Evolution.

Este README fornece:

- Instruções de instalação e configuração
- Exemplos completos de uso (Laravel e PHP puro)
- Referência detalhada da API pública da biblioteca (métodos, parâmetros, estruturas)
- Troubleshooting e FAQ

## Requisitos

- PHP >= 8.1
- Extensão cURL (usada pelo Guzzle)
- dependência: guzzlehttp/guzzle (já indicada no composer.json)

## Instalação

Instale via Composer:

```bash
composer require innovation-studios/evolution-api-plugin
```

Se estiver em um projeto Laravel, publique o arquivo de configuração:

```
php artisan vendor:publish --tag=config
```

Configuração
------------

[](#configuração-1)

O pacote espera uma configuração simples em `config/evolution.php` com as chaves:

- `api_url` — URL base da API Evolution (ex: )
- `api_key` — chave de autenticação fornecida pela API

Exemplo `.env`:

```
EVOLUTION_API_URL=https://seu-evolution.example.com
EVOLUTION_API_KEY=chave_api_aqui
```

Se não usar Laravel, pode instanciar `EvolutionApi` diretamente passando `apiKey` e `apiUrl`.

Uso Rápido
----------

[](#uso-rápido)

Exemplo mínimo (PHP puro):

```
use EvolutionApiPlugin\EvolutionApi;

$apiKey = 'SUA_CHAVE_AQUI';
$apiUrl = 'https://seu-evolution.example.com';

$evolution = new EvolutionApi($apiKey, $apiUrl);

$response = $evolution->sendTextMessage('exampleInstance', '5511999999999', 'Olá do Evolution!');
print_r($response);
```

No Laravel, o serviço é registrado via `EvolutionApiServiceProvider` e pode ser injetado ou usado pela facade `EvolutionApiFacade`.

Principais Conceitos
--------------------

[](#principais-conceitos)

- Instância: representa uma sessão/conexão com o serviço (nome identificador)
- API v1 vs v2: a biblioteca suporta duas estruturas de payloads (padrões v1.x e v2.x) — use `setApiVersion('v2')` quando precisar das estruturas v2.

Referência de API da Biblioteca
-------------------------------

[](#referência-de-api-da-biblioteca)

Todas as funções retornam o JSON decodificado (array associativo) retornado pela API Evolution.

Observação: os métodos podem lançar exceções do Guzzle (`GuzzleHttp\Exception\GuzzleException`) em caso de erro de transporte.

### \_\_construct(string $apiKey, string $apiUrl = 'localhost:8080', string $apiVersion = 'v1')

[](#__constructstring-apikey-string-apiurl--localhost8080-string-apiversion--v1)

- Descrição: cria o cliente configurado com headers padrão (accept: application/json, apikey e Content-Type).
- Parâmetros:
    - `apiKey` — chave da API (string, obrigatória)
    - `apiUrl` — URL base da API (string, opcional)
    - `apiVersion` — 'v1' ou 'v2' (padrão: 'v1')

### setApiVersion(string $version): void

[](#setapiversionstring-version-void)

- Define a versão da API usada para formatar payloads. Aceita 'v1' ou 'v2'.

### createInstance(string $instanceName, string $token, bool $qrcode = true, array $options = \[\]): array

[](#createinstancestring-instancename-string-token-bool-qrcode--true-array-options---array)

- Cria uma instância na API.
- Payloads:
    - v1: { instanceName, token, qrcode }
    - v2: aceita `options` adicionais que serão mescladas ao payload

Exemplo:

```
$resp = $evolution->createInstance('meuInstance', 'token123', true);
```

### fetchInstance(string $instanceName): array

[](#fetchinstancestring-instancename-array)

- Retorna informações sobre a(s) instância(s).

Exemplo:

```
$info = $evolution->fetchInstance('meuInstance');
```

### deleteInstance(string $instanceName): array

[](#deleteinstancestring-instancename-array)

- Remove uma instância.

Exemplo:

```
$result = $evolution->deleteInstance('meuInstance');
```

### connectInstance(string $instanceName): array

[](#connectinstancestring-instancename-array)

- Dispara a ação de conectar a instância (end-point GET /instance/connect/{instanceName}).

### connectionState(string $instanceName): array

[](#connectionstatestring-instancename-array)

- Consulta o estado da conexão de uma instância.

### sendTextMessage(string $instanceName, string $number, string $text, array $options = \[\], array $mentions = \[\]): array

[](#sendtextmessagestring-instancename-string-number-string-text-array-options---array-mentions---array)

- Envia mensagem de texto.
- Parâmetros principais:
    - `instanceName` — nome da instância (string)
    - `number` — número no formato internacional, ex: 5511999999999 (string)
    - `text` — texto da mensagem (string)
    - `options` — array de opções (delay, presence, linkPreview, quoted, etc.)
    - `mentions` — array de menções (formato depende da versão da API)

Payloads (resumo):

- v1: { number, textMessage: { text }, options?: { ... }, options.mentions?: \[...\] }
- v2: { number, text, ...options, mentioned?: \[...\] }

Exemplo v1:

```
$resp = $evolution->sendTextMessage('meuInstance', '5511999999999', 'Olá!', ['delay' => 2]);
```

Exemplo v2 (com menções):

```
$evolution->setApiVersion('v2');
$resp = $evolution->sendTextMessage('meuInstance', '5511999999999', 'Olá @fulano', ['linkPreview' => true], ['fulano'] );
```

### sendList(string $instanceName, string $number, array $listData, array $options = \[\]): array

[](#sendliststring-instancename-string-number-array-listdata-array-options---array)

- Envia uma mensagem do tipo lista.
- `listData` (v1) deve conter `listMessage` estruturado. Para v2, passe a estrutura conforme `createListStructure`.

Exemplo:

```
$list = [
  'title' => 'Menu',
  'description' => 'Escolha uma opção',
  'buttonText' => 'Abrir',
  'footerText' => 'Footer',
  'sections' => [ [ 'title' => 'Seção', 'rows' => [ [ 'title' => 'Opção 1', 'rowId' => 'op1' ] ] ] ]
];

$resp = $evolution->sendList('meuInstance', '5511999999999', $list);
```

### sendMediaMessage(string $instanceName, string $number, array $mediaData, array $options = \[\]): array

[](#sendmediamessagestring-instancename-string-number-array-mediadata-array-options---array)

- Envia imagens, áudios, vídeos e outros tipos de mídia.
- `mediaData` exemplo (v2):

```
$media = [
  'mediatype' => 'image',
  'mimetype' => 'image/jpeg',
  'caption' => 'Legenda',
  'media' => 'https://exemplo.com/foto.jpg',
  'fileName' => 'foto.jpg'
];

$resp = $evolution->sendMediaMessage('meuInstance', '5511999999999', $media);
```

### Helpers

[](#helpers)

createListStructure(...), createMediaStructure(...), createQuotedStructure(...) — utilitários que ajudam a montar os payloads v2.

Exemplos completos
------------------

[](#exemplos-completos)

### Exemplo (PHP puro)

[](#exemplo-php-puro)

```
require 'vendor/autoload.php';

use EvolutionApiPlugin\EvolutionApi;

$apiKey = getenv('EVOLUTION_API_KEY') ?: 'SUA_CHAVE';
$apiUrl = getenv('EVOLUTION_API_URL') ?: 'https://seu-evolution.example.com';

$evolution = new EvolutionApi($apiKey, $apiUrl);

try {
    $instance = 'meuInstance';
    $resp = $evolution->sendTextMessage($instance, '5511999999999', 'Mensagem de teste');
    print_r($resp);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    echo "Erro HTTP: " . $e->getMessage();
}
```

### Exemplo (Laravel Controller)

[](#exemplo-laravel-controller)

```
use EvolutionApiPlugin\EvolutionApi;

class EvolutionController extends Controller
{
    public function send(EvolutionApi $evolution)
    {
        $resp = $evolution->sendTextMessage('meuInstance', '5511999999999', 'Olá do Laravel');
        return response()->json($resp);
    }
}
```

### Chamadas curl (útil para debugging)

[](#chamadas-curl-útil-para-debugging)

Substitua API\_KEY e URL conforme seu ambiente:

```
curl -X POST "https://seu-evolution.example.com/message/sendText/meuInstance" \
  -H "accept: application/json" \
  -H "apikey: SUA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"number":"5511999999999","text":"Olá via curl"}'
```

Tratamento de erros e troubleshooting
-------------------------------------

[](#tratamento-de-erros-e-troubleshooting)

- Erros HTTP: a biblioteca propaga exceções do Guzzle. Trate com try/catch em pontos onde falhas de rede são esperadas.
- Respostas inválidas: verifique `json_decode` retornando `null` — possivelmente a API retornou HTML ou erro.
- Timeouts: use opções do Guzzle se precisar ajustar timeout (p.ex. ao instanciar `Client`).

Dicas rápidas:

- Verifique se `EVOLUTION_API_URL` inclui protocolo (https://) quando necessário.
- Confirme se a `api_key` está correta e possui permissão para os endpoints usados.
- Para desenvolvimento local, exponha a API via ngrok ou ajuste CORS conforme necessário.

Boas práticas
-------------

[](#boas-práticas)

- Não logue chaves de API em logs públicos.
- Use filas (jobs) para envios em massa.
- Reutilize instâncias do `EvolutionApi` em vez de criar novas por requisição.

FAQ
---

[](#faq)

Q: A biblioteca suporta webhooks? A: A biblioteca atual é um cliente HTTP. Para receber webhooks, implemente endpoints no seu servidor e configure a API Evolution conforme documentação do servidor Evolution.

Q: Como enviar mídia via base64? A: Em `media` envie o conteúdo em base64 se a API Evolution aceitar esse formato (ex.: `data:image/jpeg;base64,...`) ou informe a URL pública.

Contribuição
------------

[](#contribuição)

Contribuições são bem-vindas. Abra issues ou PRs com testes e descrição clara do problema.

Licença
-------

[](#licença)

MIT — veja o arquivo LICENSE.

---

###  Health Score

34

—

LowBetter than 77% of packages

Maintenance64

Regular maintenance activity

Popularity12

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity44

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% 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

Unknown

Total

1

Last Release

221d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/b467c957f4374391795d742bf1a7cdadedb8b3e717ba693b4b5d23a96705d6f7?d=identicon)[innoavtionstudios47](/maintainers/innoavtionstudios47)

---

Top Contributors

[![innovationstudios](https://avatars.githubusercontent.com/u/150537146?v=4)](https://github.com/innovationstudios "innovationstudios (13 commits)")

---

Tags

apimessagingwhatsappevolution-apiwhatsapp-apievolution

### Embed Badge

![Health badge](/badges/innovation-studios-evolution-api-plugin/health.svg)

```
[![Health](https://phpackages.com/badges/innovation-studios-evolution-api-plugin/health.svg)](https://phpackages.com/packages/innovation-studios-evolution-api-plugin)
```

###  Alternatives

[scriptdevelop/whatsapp-manager

Paquete para manejo de WhatsApp Business API en Laravel

762.6k](/packages/scriptdevelop-whatsapp-manager)[crenspire/laravel-whatsapp

Laravel WhatsApp Business API package

133.0k](/packages/crenspire-laravel-whatsapp)

PHPackages © 2026

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