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 2025-10-10 02:26 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.0

MIT

• Innovation Studios

• api
• messaging
• whatsapp
• evolution
• whatsapp-api
• evolution-api

README

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

Instalação

Instale o plugin via Composer:

composer require innovation-studios/evolution-api-plugin

Configuração

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)

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

Criar Instância

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

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

$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

$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

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

Excluir Instância

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

Exemplos

Laravel

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

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

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

• api_url — URL base da API Evolution (ex: https://evolution.example.com)
• 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

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

• 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

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')

• 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

• 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

• 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

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

Exemplo:

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

deleteInstance(string $instanceName): array

• Remove uma instância.

Exemplo:

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

connectInstance(string $instanceName): array

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

connectionState(string $instanceName): array

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

sendTextMessage(string $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

• 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

• 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

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

Exemplos completos

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)

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)

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

• 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

• 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

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ções são bem-vindas. Abra issues ou PRs com testes e descrição clara do problema.

Licença

MIT — veja o arquivo LICENSE.