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

​
1. Install and create the client

npm install @vzaps/sdk

import { VZapsClient } from '@vzaps/sdk';

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

​
2. Validate authentication

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

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

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

​
4. Create an instance

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

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: 
const resumed = await vzaps.instances.resumeSubscription('VZ...', {
  instanceToken: 'instance-token',
});

​
6. Pair WhatsApp

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

console.dir(status, { depth: null });
Fetch QR code: 
const qr = await vzaps.sessions.qr('VZ...', {
  instanceToken: 'instance-token',
});

console.dir(qr, { depth: null });
Fetch pairing code by phone: 
const pairCode = await vzaps.sessions.pairCode('VZ...', '5511999999999', {
  instanceToken: 'instance-token',
});

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

​
7. Configure webhook

See Webhooks for full configuration, logs, and examples. 
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 for subscription details, ack, and reconnection. 
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

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

​
10. Send media

Image: 
await vzaps.messages.sendImage({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  image: 'https://example.com/image.jpg',
  caption: 'Image sent with VZaps',
});
Document: 
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 for all send types and payloads.

​
11. Check queues

See Queues to list, remove, and purge queues.

​
12. Handle errors

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;
}