Skip to main content
The official VZaps PHP SDK wraps authentication, HTTP calls, required headers, realtime events, and the main public API resources. Use this SDK when integrating VZaps into PHP backends, CLIs, workers, Laravel/Symfony commands, jobs, and server-to-server automation.

​
Requirements

ResourceVersion
PHP8.1 or higher
Composer2.x recommended
Extensionjson
HTTPGuzzle 7, installed by the package
Do not expose clientSecret or instanceToken in a public frontend. Prefer using the SDK in backends, commands, jobs, and server-to-server automation.

​
Install

composer require vzaps/sdk
For realtime WebSocket usage in CLI/workers, also install the optional transport: 
composer require textalk/websocket

​
Create the client

use VZaps\Sdk\VZapsClient;

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

​
Credentials

The SDK uses two credential groups:
CredentialWhere to useDescription
clientTokennew VZapsClient()Public account token, also sent as X-Client-Token.
clientSecretnew VZapsClient()Secret used by the SDK to obtain and refresh JWTs.
instanceTokenOn each instance callInstance token, sent as X-Instance-Token.
instanceToken is not stored on the global client. Always pass it in calls that operate an instance: 
$vzaps->messages()->sendText([
    'instanceId' => 'VZ...',
    'instanceToken' => getenv('VZAPS_INSTANCE_TOKEN'),
    'phone' => '5511999999999',
    'message' => 'Hello from VZaps',
]);

​
Automatic authentication

The SDK obtains the JWT automatically using clientToken and clientSecret, caches the token in memory, and refreshes it before expiry. You rarely need to call the token manually. When integrating with custom HTTP code: 
$accessToken = $vzaps->auth()->getAccessToken();

​
Client options

OptionTypeDefaultUse
clientTokenstring-Required. Account token.
clientSecretstring-Required. Account secret.
timeoutSecondsfloat30.0HTTP timeout in seconds.
tokenSkewSecondsint60Refresh JWT before actual expiry.
httpClientPsr\Http\Client\ClientInterfaceGuzzleCustomize HTTP transport for tests, proxy, or TLS.
webSocketFactorycallabletextalk/websocket when installedCustomize WebSocket transport.
userAgentstringVZaps.SDK.PHP/<version>User-Agent header on HTTP requests.
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

In simple PHP scripts: 
require __DIR__ . '/vendor/autoload.php';

use VZaps\Sdk\VZapsClient;
In Laravel, Symfony, and other frameworks, use your project Composer autoload and register VZapsClient as a service/singleton when useful. 
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=instance-token

​
Response typing

By default, responses are PHP arrays decoded from API JSON because the contract can evolve. 
/** @var array<string, mixed> $instances */
$instances = $vzaps->instances()->list([
    'page' => 1,
    'pageSize' => 20,
]);
For main requests, you can use DTOs with named arguments: 
use VZaps\Sdk\Models\Messages\SendTextMessageRequest;

$vzaps->messages()->sendText(new SendTextMessageRequest(
    instanceId: 'VZ...',
    instanceToken: getenv('VZAPS_INSTANCE_TOKEN'),
    phone: '5511999999999',
    message: 'Hello from VZaps',
));
For new or advanced public contract fields, use arrays or GenericInstanceRequest.

​
Next steps