README

MVO WHATS PHP

Conecte. Receba. Envie. Tudo no seu projeto PHP.

Biblioteca nativa para integrar o protocolo WhatsApp a workers, aplicações e APIs PHP.

Instalação · Primeira conexão · Exemplos · Documentação web · LLMs e MCP · llms.txt

PHP 8.2+ · Linux e Windows · Composer · Sessões persistentes · Eventos

Use uma instalação da biblioteca para atender várias contas, cada uma com seu próprio identificador, credenciais e processo de conexão. O transporte, a criptografia e os serviços da biblioteca executam em PHP, sem exigir Node.js ou uma API intermediária.

Comece pelo terminal

Com PHP e as extensões necessárias instalados:

git clone https://github.com/mmhospedagem/mvo-whats-php.git
cd mvo-whats-php
composer install --no-dev --prefer-dist
php examples/connect.php --session=demo --mode=qr

Escaneie o QR em WhatsApp → Aparelhos conectados → Conectar um aparelho. O exemplo atualiza o QR enquanto ele muda e mantém o processo conectado. Execute novamente com a mesma sessão para restaurar um vínculo válido.

Para usar no seu próprio projeto, instale o pacote mmhospedagem/mvo-whats-php pelo Composer:

composer require "mmhospedagem/mvo-whats-php:^1.0"

O Composer encontra o pacote no Packagist, sem configurar repositório VCS. Veja os requisitos e a configuração completa no guia de instalação.

Integre diretamente no PHP

Os comandos de terminal são exemplos. Sua aplicação controla o cliente pelas próprias classes da biblioteca:

<?php
declare(strict_types=1);

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

use MVO\Auth\QrCode;
use MVO\WaClient;

$client = new WaClient(
    sessionId: 'cliente-demo',
    authDirectory: __DIR__.'/storage/whatsapp',
);

$client->on('auth_qr', static function (array $event): void {
    // Encaminhe este SVG somente ao usuário autorizado a vincular a conta.
    file_put_contents(__DIR__.'/storage/qr-demo.svg', QrCode::svg($event['qr']));
});

$client->on('message', static function (array $event): void {
    echo ($event['from'] ?? '').': '.($event['text'] ?? '[mídia]').PHP_EOL;
});

try {
    $client->connect();
    while ($client->isRunning()) {
        $client->poll(0.25);
        // Consuma sua fila e chame sendText()/sendMessage() quando conectado.
    }
} finally {
    $client->disconnect();
}

Salve como worker.php e execute php worker.php. Mantenha storage fora da raiz pública da aplicação. Veja como enviar mensagens no loop, conectar por código e integrar eventos à sua API.

O que você pode construir

Área	Recursos	Guia
Conexão	QR rotativo, código, eventos, restauração e reconexão	Conexão
Mensagens	Texto, mídia, localização, contatos, reações, enquetes e interativos	Tipos de mensagens
Mídia	Upload, download verificado, arquivos e streams	Mídia
Conversas	Histórico, contatos, recibos, presença e sincronização de estado	Histórico · Presença
Grupos e comunidades	Administração, participantes, convites e configurações	Serviços · Comunidades
Business	Perfil comercial, catálogo, produtos e ferramentas de negócio	Serviços
Status e canais	Publicações, consultas, interações e gerenciamento	Status · Canais
Persistência	SQLite e backends configuráveis para estado e histórico	Armazenamento
Extensões	Formulários, agendamentos, plugins, MCP e chamadas opcionais	Formulários · Agendamentos · MCP · VoIP

Uma biblioteca, várias sessões

$client = new MVO\WaClient(
    sessionId: 'cliente-001',
    authDirectory: '/var/lib/minha-aplicacao/whatsapp',
);

Para 60 clientes, use uma instalação do código e 60 sessões isoladas. A arquitetura recomendada é um worker por sessão, supervisionado pela sua aplicação. Não abra dois processos para o mesmo identificador e diretório: a biblioteca usa um lock para impedir conexões concorrentes. Veja a organização completa.

Guias para avançar

Instalar no Ubuntu 24.04 ou Windows.
Conectar, persistir a sessão e trocar mensagens.
Copiar exemplos de mensagens, eventos e serviços.
Consultar identidade da conta e PN/LID.
Explorar histórico e app-state · App-state.
Consultar formatos de Flow e suas limitações.
Executar o simulador local e configurar o desenvolvimento.
Ler medições e metodologia de desempenho.
Integrar LLMs e agentes com MCP, ou fornecer llms-full.txt como contexto completo ao modelo.

Participe

Encontrou um problema ou quer contribuir? Veja como contribuir, os canais de relato e o changelog. A documentação também está disponível offline em docs/index.html.

Compatibilidade e operação

A biblioteca implementa o protocolo WhatsApp e não é um produto oficial da Meta. A disponibilidade de um recurso e sua renderização dependem da conta, do servidor e do aplicativo receptor. Consulte a matriz de recursos e os guias específicos; testes locais não comprovam suporte universal em contas reais.

O processo PHP precisa continuar executando para receber eventos e manter a conexão. Credenciais e estado persistem no disco; disconnect() encerra o transporte preservando o vínculo, enquanto logout() solicita a remoção do aparelho. Uma sessão revogada no celular exige novo pareamento.

Mensagens funcionam com as extensões PHP descritas na instalação. Alguns recursos de mídia e chamadas utilizam FFmpeg ou bibliotecas nativas opcionais instaladas separadamente. No Linux, essas dependências usam os binários da plataforma; DLLs de Windows não são usadas no Ubuntu.

Licença

Distribuído sob a licença do projeto. Consulte também os avisos e atribuições de terceiros.

mmhospedagem / mvo-whats-php

Package info

Security

Statistics