Pular para o conteúdo principal
Este guia mostra o caminho recomendado para sair do zero até uma instância conectada enviando mensagens pela VZaps.

​
1. Instale e crie o cliente

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. Valide autenticação

const jwt = await vzaps.auth.getAccessToken();
console.log(jwt.slice(0, 16));
Na maioria dos fluxos, você não precisa chamar getAccessToken(). Os recursos do SDK fazem isso automáticamente.

​
3. Liste instâncias existentes

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

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

​
4. Crie uma instância

const created = await vzaps.instances.create({
  name: 'Atendimento Comercial',
  webhook: 'https://example.com/webhooks/vzaps',
  eventsSubscribe: ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
});

console.dir(created, { depth: null });
Guarde do response:
  • id: identificador da instância.
  • token: token da instância. Use como instanceToken nas chamadas da instância.

​
5. Assine a instância

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

console.dir(subscription, { depth: null });
Se houver um cancelamento agendado e você quiser reativar a assinatura: 
const resumed = await vzaps.instances.resumeSubscription('VZ...', {
  instanceToken: 'instance-token',
});

​
6. Pareie o WhatsApp

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

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

console.dir(qr, { depth: null });
Buscar código de pareamento por telefone: 
const pairCode = await vzaps.sessions.pairCode('VZ...', '5511999999999', {
  instanceToken: 'instance-token',
});

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

​
7. Configure webhook

Veja Webhooks para configuração completa, logs e exemplos. 
await vzaps.webhooks.set({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  webhookURL: 'https://example.com/webhooks/vzaps',
  events: ['Message', 'ReadReceipt', 'Connected', 'Disconnected'],
});

​
8. Assine realtime

Veja Realtime para detalhes de assinatura, ack e reconexão. 
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. Envie a primeira mensagem

await vzaps.messages.sendText({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  message: 'Olá! Esta mensagem foi enviada pela VZaps.',
});

​
10. Envie mídia

Imagem: 
await vzaps.messages.sendImage({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  image: 'https://example.com/image.jpg',
  caption: 'Imagem enviada pela VZaps',
});
Documento: 
await vzaps.messages.sendDocument({
  instanceId: 'VZ...',
  instanceToken: 'instance-token',
  phone: '5511999999999',
  document: 'https://example.com/contrato.pdf',
  fileName: 'contrato.pdf',
  caption: 'Segue o contrato',
});
Veja Mensagens para todos os tipos de envio e payloads.

​
11. Acompanhe filas

Veja Filas para listar, remover e limpar filas.

​
12. Trate erros

import {
  VZapsAuthenticationError,
  VZapsError,
  VZapsTimeoutError,
} from '@vzaps/sdk';

try {
  await vzaps.messages.sendText({
    instanceId: 'VZ...',
    instanceToken: 'instance-token',
    phone: '5511999999999',
    message: 'Olá',
  });
} catch (error) {
  if (error instanceof VZapsAuthenticationError) {
    console.error('Credenciais inválidas');
  } else if (error instanceof VZapsTimeoutError) {
    console.error('Request expirou');
  } else if (error instanceof VZapsError) {
    console.error(error.status, error.message, error.details);
  }

  throw error;
}