> ## Documentation Index
> Fetch the complete documentation index at: https://docs.vzaps.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> How to install, authenticate, and configure the official VZaps TypeScript SDK

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` |

<Tip>
  Do not expose `clientSecret` or `instanceToken` in public front ends. Prefer using the SDK in backends, API routes, jobs, and server-to-server automations.
</Tip>

## Install

```bash theme={null}
npm install @vzaps/sdk
```

```bash theme={null}
yarn add @vzaps/sdk
```

```bash theme={null}
pnpm add @vzaps/sdk
```

## Create the client

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
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:

```ts theme={null}
import { VZapsClient } from '@vzaps/sdk';
```

CommonJS:

```js theme={null}
const { VZapsClient } = require('@vzaps/sdk');
```

## Recommended environment variables

```bash theme={null}
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:

```ts theme={null}
interface InstanceListResponse {
  data: Array<{
    id: string;
    name: string;
    billingStatus: string;
  }>;
}

const instances = await vzaps.instances.list<InstanceListResponse>({
  page: 1,
  pageSize: 20,
});
```

## Next steps

* Follow the [Starter Guide](/en/sdk/typescript/starter-guide) to create an instance, subscribe it, pair WhatsApp, and send the first message.
* See [Messages](/en/sdk/typescript/messages) for every send method.
* See [Instances and billing](/en/sdk/typescript/instances-and-billing), [Session](/en/sdk/typescript/session), and [Chats](/en/sdk/typescript/chats) for core instance resources.
* See [Webhooks](/en/sdk/typescript/webhooks), [Queues](/en/sdk/typescript/queues), [Groups](/en/sdk/typescript/groups), [TypeBot](/en/sdk/typescript/typebot), and [Chatwoot](/en/sdk/typescript/chatwoot) for configuration and integrations.