The official VZaps TypeScript SDK wraps authentication, HTTP calls, required headers, realtime events, and the main public API resources.
Use this SDK for Node.js applications, workers, TypeScript backends, CLIs, and server-to-server automations.
Requirements
| Resource | Version |
|---|
| Node.js | 18 or higher |
| TypeScript | 5.x recommended |
| Package manager | npm, yarn, or pnpm |
Do not expose clientSecret or instanceToken in public front ends. Prefer using the SDK in backends, API routes, jobs, and server-to-server automations.
Install
Create the client
import { VZapsClient } from '@vzaps/sdk';
const vzaps = new VZapsClient({
clientToken: process.env.VZAPS_CLIENT_TOKEN!,
clientSecret: process.env.VZAPS_CLIENT_SECRET!,
});
Credentials
The SDK uses two credential groups:
| Credential | Where to use | Description |
|---|
clientToken | new VZapsClient() | Account client token, also sent as X-Client-Token. |
clientSecret | new VZapsClient() | Secret used by the SDK to obtain and refresh JWTs. |
instanceToken | On each instance call | Instance token, sent as X-Instance-Token. |
instanceToken is not stored on the global client. Always pass it in calls that operate an instance:
await vzaps.messages.sendText({
instanceId: 'VZ...',
instanceToken: process.env.VZAPS_INSTANCE_TOKEN!,
phone: '5511999999999',
message: 'Hello from VZaps',
});
Automatic authentication
The SDK obtains a JWT automatically with clientToken and clientSecret, caches it in memory, and refreshes it before expiry.
You rarely need to call auth.getAccessToken() manually. When you need to integrate with custom logic:
const accessToken = await vzaps.auth.getAccessToken();
Client options
| Option | Type | Default | Use |
|---|
clientToken | string | - | Required. Account client token. |
clientSecret | string | - | Required. Account secret. |
timeoutMs | number | 30000 | HTTP timeout in milliseconds. |
tokenSkewMs | number | 60000 | Refresh JWT before actual expiry. |
fetch | FetchLike | globalThis.fetch | Customize HTTP transport in tests or specific runtimes. |
webSocketFactory | WebSocketFactory | ws in Node / WebSocket in browsers | Customize WebSocket transport. |
userAgent | string | - | User-Agent header for HTTP requests. |
ESM and CommonJS
ESM:
import { VZapsClient } from '@vzaps/sdk';
const { VZapsClient } = require('@vzaps/sdk');
Recommended environment variables
VZAPS_CLIENT_TOKEN=your-client-token
VZAPS_CLIENT_SECRET=your-client-secret
VZAPS_INSTANCE_ID=VZ...
VZAPS_INSTANCE_TOKEN=your-instance-token
Typing responses
Responses default to unknown because the API can evolve. You can type expected responses with generics:
interface InstanceListResponse {
data: Array<{
id: string;
name: string;
billingStatus: string;
}>;
}
const instances = await vzaps.instances.list<InstanceListResponse>({
page: 1,
pageSize: 20,
});
Next steps
