> ## 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.

# Starter Guide

> Complete TypeScript SDK flow: authenticate, create an instance, subscribe, pair, configure events, and send messages

This guide shows the recommended path from zero to a connected instance sending messages through VZaps.

## 1. Install and create the client

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

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

const vzaps = new VZapsClient({
  clientToken: process.env.VZAPS_CLIENT_TOKEN!,
  clientSecret: process.env.VZAPS_CLIENT_SECRET!,
});
```

## 2. Validate authentication

```ts theme={null}
const jwt = await vzaps.auth.getAccessToken();
console.log(jwt.slice(0, 16));
```

In most flows you do not need to call `getAccessToken()`. SDK resources do it automatically.

## 3. List existing instances

```ts theme={null}
const instances = await vzaps.instances.list({
  page: 1,
  pageSize: 20,
  search: 'support',
});

console.dir(instances, { depth: null });
```

## 4. Create an instance

```ts theme={null}
const created = await vzaps.instances.create({
  name: 'Sales Support',
  webhook: 'https://example.com/webhooks/vzaps',
  eventsSubscribe: ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
});

console.dir(created, { depth: null });
```

Store from the response:

* `id`: instance identifier.
* `token`: instance token. Use it as `instanceToken` in instance calls.

## 5. Subscribe the instance

```ts theme={null}
const subscription = await vzaps.instances.subscribe(
  'VZ...',
  {},
  { instanceToken: 'instance-token' },
);

console.dir(subscription, { depth: null });
```

If a cancellation is scheduled and you want to reactivate the subscription:

```ts theme={null}
const resumed = await vzaps.instances.resumeSubscription('VZ...', {
  instanceToken: 'instance-token',
});
```

## 6. Pair WhatsApp

Check status:

```ts theme={null}
const status = await vzaps.sessions.status('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(status, { depth: null });
```

Fetch QR code:

```ts theme={null}
const qr = await vzaps.sessions.qr('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(qr, { depth: null });
```

Fetch pairing code by phone:

```ts theme={null}
const pairCode = await vzaps.sessions.pairCode('VZ...', '5511999999999', {
  instanceToken: 'instance-token',
});

console.dir(pairCode, { depth: null });
```

## 7. Configure webhook

See [Webhooks](/en/sdk/typescript/webhooks) for full configuration, logs, and examples.

```ts theme={null}
await vzaps.webhooks.set({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  webhookURL: 'https://example.com/webhooks/vzaps',
  events: ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
});
```

## 8. Subscribe to realtime

See [Realtime](/en/sdk/typescript/realtime) for subscription details, ack, and reconnection.

```ts theme={null}
const subscription = await vzaps.events.subscribe({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  events: ['Message', 'Connected', 'Disconnected'],
  reconnect: true,
});

subscription.on('Message', (event) => {
  console.log(event.id);
  console.dir(event.data, { depth: null });
});

subscription.on('error', (error) => {
  console.error(error);
});
```

## 9. Send the first message

```ts theme={null}
await vzaps.messages.sendText({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  message: 'Hello! This message was sent with VZaps.',
});
```

## 10. Send media

Image:

```ts theme={null}
await vzaps.messages.sendImage({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  image: 'https://example.com/image.jpg',
  caption: 'Image sent with VZaps',
});
```

Document:

```ts theme={null}
await vzaps.messages.sendDocument({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  document: 'https://example.com/contract.pdf',
  fileName: 'contract.pdf',
  caption: 'Here is the contract',
});
```

See [Messages](/en/sdk/typescript/messages) for all send types and payloads.

## 11. Check queues

See [Queues](/en/sdk/typescript/queues) to list, remove, and purge queues.

## 12. Handle errors

```ts theme={null}
import {
  VZapsAuthenticationError,
  VZapsError,
  VZapsTimeoutError,
} from '@vzaps/sdk';

try {
  await vzaps.messages.sendText({
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    phone: '5511999999999',
    message: 'Hello',
  });
} catch (error) {
  if (error instanceof VZapsAuthenticationError) {
    console.error('Invalid credentials');
  } else if (error instanceof VZapsTimeoutError) {
    console.error('Request timed out');
  } else if (error instanceof VZapsError) {
    console.error(error.status, error.message, error.details);
  }

  throw error;
}
```