Pular para o conteúdo principal
O SDK PHP oficial da VZaps encapsula autenticação, chamadas HTTP, headers obrigatórios, eventos realtime e os principais recursos da API pública. Use este SDK quando quiser integrar a VZaps em backends PHP, CLIs, workers, comandos Laravel/Symfony, jobs e automações server-to-server.

​
Requisitos

RecursoVersão
PHP8.1 ou superior
Composer2.x recomendado
Extensãojson
HTTPGuzzle 7, instalado pelo pacote
Não exponha clientSecret nem instanceToken em front-end público. Prefira usar o SDK em backend, comandos, jobs e automações server-to-server.

​
Instalar

composer require vzaps/sdk
Para usar realtime WebSocket em CLI/worker, instale também o transporte opcional: 
composer require textalk/websocket

​
Criar o cliente

use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
);

​
Credenciais

O SDK usa dois grupos de credenciais:
CredencialOnde usarDescrição
clientTokennew VZapsClient()Token público da conta, usado também no header X-Client-Token.
clientSecretnew VZapsClient()Segredo usado pelo SDK para obter e renovar o JWT.
instanceTokenEm cada chamada da instânciaToken da instância, enviado como X-Instance-Token.
O instanceToken não fica no cliente global. Passe sempre na chamada que opera uma instância: 
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => getenv('VZAPS_INSTANCE_TOKEN'),
    'phone' => '5511999999999',
    'message' => 'Olá pela VZaps',
]);

​
Autenticação automática

O SDK obtém o JWT automaticamente usando clientToken e clientSecret, guarda o token em memória e renova antes do vencimento. Você raramente precisa chamar o token manualmente. Quando precisar integrar com código HTTP próprio: 
$accessToken = $vzaps->auth()->getAccessToken();

​
Opções do cliente

OpçãoTipoPadrãoUso
clientTokenstring-Obrigatório. Token da conta.
clientSecretstring-Obrigatório. Segredo da conta.
timeoutSecondsfloat30.0Timeout HTTP em segundos.
tokenSkewSecondsint60Renovar JWT antes do vencimento real.
httpClientPsr\Http\Client\ClientInterfaceGuzzleCustomizar transporte HTTP em testes, proxy ou TLS.
webSocketFactorycallabletextalk/websocket quando instaladoCustomizar WebSocket.
userAgentstringVZaps.SDK.PHP/<versão>Header User-Agent em requests HTTP.
use GuzzleHttp\Client;
use VZaps\Sdk\VZapsClient;

$vzaps = new VZapsClient(
    clientToken: getenv('VZAPS_CLIENT_TOKEN'),
    clientSecret: getenv('VZAPS_CLIENT_SECRET'),
    timeoutSeconds: 10,
    httpClient: new Client([
        'timeout' => 10,
        'http_errors' => false,
    ]),
);

​
Composer autoload

Em scripts PHP simples: 
require __DIR__ . '/vendor/autoload.php';

use VZaps\Sdk\VZapsClient;
Em Laravel, Symfony e outros frameworks, use o autoload do Composer do próprio projeto e registre VZapsClient como service/singleton quando fizer sentido.

​
Variáveis de ambiente recomendadas

VZAPS_CLIENT_TOKEN=seu-client-token
VZAPS_CLIENT_SECRET=seu-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=token-da-instância

​
Tipagem de respostas

Por padrão, respostas são arrays PHP decodificados do JSON da API, porque o contrato pode evoluir. 
/** @var array<string, mixed> $instances */
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 20,
]);
Para requests principais, você pode usar DTOs com named arguments: 
use VZaps\Sdk\Models\Messages\SendTextMessageRequest;

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: getenv('VZAPS_INSTANCE_TOKEN'),
    phone: '5511999999999',
    message: 'Olá pela VZaps',
));
Para campos novos ou avançados do contrato público, use arrays ou GenericInstanceRequest.

​
Próximos passos