willenrocha/zapapi-php

SDK oficial PHP para a API ZapApi — WhatsApp para desenvolvedores

dev-main 2026-04-06 21:36 UTC

Requires

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

Requires (Dev)

• phpunit/phpunit: ^10.0

MIT

• INOVIX

• api
• sms
• messaging
• whatsapp
• zapapi
• willenrocha

README

SDK oficial PHP para a ZapApi — WhatsApp API para desenvolvedores.

Requisitos

• PHP 8.1+
• Extensao JSON
• Conta na ZapApi com API key

Instalacao

composer require willenrocha/zapapi-php

Quick Start

use Inovix\ZapApi\Client;

$client = new Client('sua-api-key');

// Criar uma sessao
$session = $client->sessions->create('minha-sessao');

// Obter QR Code para conectar
$qr = $client->sessions->getQrCode($session['id']);

// Enviar mensagem de texto
$client->messages->sendText(
    sessionId: $session['id'],
    to: '5511999999999',
    text: 'Ola! Mensagem enviada via ZapApi.',
);

Configuracao

$client = new Client('sua-api-key', [
    'base_url' => 'https://api.zapapi.net',  // padrao
    'timeout'  => 30,                         // segundos
]);

Referencia da API

Sessoes

// Criar sessao
$session = $client->sessions->create('nome-da-sessao');

// Listar sessoes
$sessions = $client->sessions->list();

// Obter sessao
$session = $client->sessions->get('session-id');

// QR Code
$qr = $client->sessions->getQrCode('session-id');

// Conectar / Desconectar
$client->sessions->connect('session-id');
$client->sessions->disconnect('session-id');

// Deletar sessao
$client->sessions->delete('session-id');

// Perfil da sessao
$profile = $client->sessions->getProfile('session-id');
$client->sessions->updateProfile('session-id', [
    'name' => 'Novo Nome',
    'status' => 'Usando ZapApi',
]);

Mensagens

// Texto
$client->messages->sendText('session-id', '5511999999999', 'Ola!');

// Midia (imagem, video, audio, documento)
$client->messages->sendMedia(
    sessionId: 'session-id',
    to: '5511999999999',
    mediaType: 'image',
    media: 'https://exemplo.com/foto.jpg',
    caption: 'Veja esta imagem!',
);

// Localizacao
$client->messages->sendLocation(
    sessionId: 'session-id',
    to: '5511999999999',
    latitude: -23.5505,
    longitude: -46.6333,
    name: 'Sao Paulo',
    address: 'Sao Paulo, SP, Brasil',
);

// Contato
$client->messages->sendContact('session-id', '5511999999999', [
    'fullName' => 'Maria Silva',
    'phoneNumber' => '5511888888888',
]);

// Enquete
$client->messages->sendPoll(
    sessionId: 'session-id',
    to: '5511999999999',
    name: 'Qual sua cor favorita?',
    options: ['Azul', 'Vermelho', 'Verde'],
);

// Reacao
$client->messages->sendReaction('session-id', '5511999999999', 'msg-id', "\u{1F44D}");

// Sticker
$client->messages->sendSticker('session-id', '5511999999999', 'https://exemplo.com/sticker.webp');

// Botoes e lista
$client->messages->sendButtons('session-id', [
    'to' => '5511999999999',
    'text' => 'Escolha uma opcao:',
    'buttons' => [
        ['id' => '1', 'text' => 'Opcao 1'],
        ['id' => '2', 'text' => 'Opcao 2'],
    ],
]);

$client->messages->sendList('session-id', [
    'to' => '5511999999999',
    'title' => 'Menu',
    'buttonText' => 'Ver opcoes',
    'sections' => [
        [
            'title' => 'Secao 1',
            'rows' => [
                ['id' => '1', 'title' => 'Item 1', 'description' => 'Descricao'],
            ],
        ],
    ],
]);

// Deletar mensagem
$client->messages->delete('session-id', '5511999999999', 'msg-id');

// Marcar como lida
$client->messages->markAsRead('session-id', '5511999999999', 'msg-id');

// Enviar digitando
$client->messages->sendTyping('session-id', '5511999999999', duration: 5);

Grupos

// Criar grupo
$group = $client->groups->create('session-id', 'Nome do Grupo', [
    '5511999999999',
    '5511888888888',
]);

// Listar grupos
$groups = $client->groups->list('session-id');

// Obter grupo
$group = $client->groups->get('session-id', 'group-id');

// Atualizar grupo
$client->groups->update('session-id', 'group-id', [
    'subject' => 'Novo Nome',
    'description' => 'Nova descricao',
]);

// Gerenciar participantes
$client->groups->addParticipants('session-id', 'group-id', ['5511999999999']);
$client->groups->removeParticipants('session-id', 'group-id', ['5511999999999']);
$client->groups->promoteParticipants('session-id', 'group-id', ['5511999999999']);
$client->groups->demoteParticipants('session-id', 'group-id', ['5511999999999']);

// Link de convite
$link = $client->groups->inviteLink('session-id', 'group-id');

// Sair do grupo
$client->groups->leave('session-id', 'group-id');

Contatos

// Verificar se numero tem WhatsApp
$result = $client->contacts->check('session-id', '5511999999999');

// Verificar em lote
$results = $client->contacts->checkBatch('session-id', [
    '5511999999999',
    '5511888888888',
]);

// Foto de perfil
$picture = $client->contacts->profilePicture('session-id', '5511999999999');

Webhooks

// Criar webhook
$webhook = $client->webhooks->create('https://meusite.com/webhook', [
    'message.received',
    'message.sent',
    'session.status',
]);

// Listar webhooks
$webhooks = $client->webhooks->list();

// Obter webhook
$webhook = $client->webhooks->get('webhook-id');

// Atualizar webhook
$client->webhooks->update('webhook-id', [
    'url' => 'https://meusite.com/novo-webhook',
    'events' => ['message.received'],
]);

// Deletar webhook
$client->webhooks->delete('webhook-id');

// Ver entregas
$deliveries = $client->webhooks->deliveries('webhook-id');

// Testar webhook
$client->webhooks->test('webhook-id');

Conta

// Obter dados da conta
$account = $client->account->get();

// Atualizar conta
$client->account->update(['name' => 'Minha Empresa']);

// Uso / consumo
$usage = $client->account->usage();

// API Keys
$keys = $client->account->apiKeys();
$newKey = $client->account->createApiKey('chave-producao');
$client->account->revokeApiKey('key-id');

Verificacao de Webhooks

Valide assinaturas de webhook para garantir a autenticidade das requisicoes:

use Inovix\ZapApi\Webhook;

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_ZAPAPI_SIGNATURE'] ?? '';
$secret = 'seu-webhook-secret';

if (Webhook::verify($payload, $signature, $secret)) {
    $event = json_decode($payload, true);
    // Processar evento...
} else {
    http_response_code(401);
    exit('Assinatura invalida');
}

Tratamento de Erros

use Inovix\ZapApi\Exceptions\AuthenticationException;
use Inovix\ZapApi\Exceptions\RateLimitException;
use Inovix\ZapApi\Exceptions\ValidationException;
use Inovix\ZapApi\Exceptions\ZapApiException;

try {
    $client->messages->sendText('session-id', '5511999999999', 'Ola!');
} catch (AuthenticationException $e) {
    // API key invalida ou expirada
    echo "Erro de autenticacao: " . $e->getMessage();
} catch (RateLimitException $e) {
    // Limite de requisicoes excedido
    echo "Tente novamente em: " . $e->getRetryAfter() . " segundos";
} catch (ValidationException $e) {
    // Dados invalidos
    echo "Erros de validacao: ";
    print_r($e->getErrors());
} catch (ZapApiException $e) {
    // Outro erro da API
    echo "Erro [{$e->getStatusCode()}]: " . $e->getMessage();
}

Licenca

MIT -- veja LICENSE para detalhes.

Links

• Site
• Documentacao da API
• Suporte