Skip to main content

TypeScript SDK

The official TypeScript SDK for ZapyAPI provides a type-safe, easy-to-use interface for interacting with your WhatsApp instances.

Installation​

npm install @zapyapi/sdk
# or
yarn add @zapyapi/sdk
# or
pnpm add @zapyapi/sdk

Quick Start​

import { ZapyClient } from '@zapyapi/sdk';

const client = new ZapyClient({
  apiKey: 'your-api-key',
});

// Send a text message
const result = await client.messages.sendText('my-instance', {
  to: '5511999999999',
  message: 'Hello from ZapyAPI SDK!'
});

console.log('Message sent:', result.messageId);

Client Configuration​

import { ZapyClient } from '@zapyapi/sdk';

const client = new ZapyClient({
  // Required: Your API key from the dashboard
  apiKey: 'your-api-key',

  // Optional: Base URL (defaults to production)
  baseUrl: 'https://api.zapyapi.com/api',

  // Optional: Request timeout in milliseconds (default: 30000)
  timeout: 30000,

  // Optional: Custom headers
  headers: {
    'X-Custom-Header': 'value'
  }
});

Available Resources​

Instances​

Manage your WhatsApp instances:

// List all instances
const { data: instances } = await client.instances.list();

// Get QR code for connecting
const qr = await client.instances.getQRCode('my-instance');
console.log('Scan this QR:', qr.qrCode);

// Restart an instance
await client.instances.restart('my-instance');

// Logout an instance
await client.instances.logout('my-instance');

Messages​

Send and manage messages:

// Send text message
await client.messages.sendText('my-instance', {
  to: '5511999999999',
  message: 'Hello!',
  quoteMessageId: 'optional-message-id-to-reply'
});

// Send image
await client.messages.sendImage('my-instance', {
  to: '5511999999999',
  image: 'https://example.com/image.jpg', // URL or base64
  caption: 'Check this out!',
  viewOnce: false
});

// Send video
await client.messages.sendVideo('my-instance', {
  to: '5511999999999',
  video: 'https://example.com/video.mp4',
  caption: 'Watch this video!'
});

// Send audio note (voice message)
await client.messages.sendAudioNote('my-instance', {
  to: '5511999999999',
  audio: 'data:audio/ogg;base64,...'
});

// Send audio file
await client.messages.sendAudioFile('my-instance', {
  to: '5511999999999',
  audio: 'https://example.com/audio.mp3'
});

// Send document
await client.messages.sendDocument('my-instance', {
  to: '5511999999999',
  document: 'https://example.com/file.pdf',
  fileName: 'report.pdf',
  caption: 'Here is the report'
});

// Forward a message
await client.messages.forward('my-instance', {
  to: '5511999999999',
  messageId: 'original-message-id'
});

// Edit a message
await client.messages.edit('my-instance', {
  messageId: 'message-id',
  message: 'Updated text'
});

// Mark as read
await client.messages.read('my-instance', {
  messageId: 'message-id'
});

// Delete a message
await client.messages.delete('my-instance', {
  messageId: 'message-id'
});

// Get media download link
const media = await client.messages.getMediaDownloadLink('my-instance', 'message-id');
console.log('Download URL:', media.url);

Enums​

The SDK exports type-safe enums for common values:

import {
  WebhookEventType,
  InstanceStatus,
  MessageAckStatus,
  MessageType,
  WebhookQueueStatus,
  ConnectionStatus
} from '@zapyapi/sdk';

// Check instance status
if (instance.status === InstanceStatus.CONNECTED) {
  console.log('Ready to send messages!');
}

// Handle webhook events
if (event.event === WebhookEventType.MESSAGE) {
  console.log('New message received!');
}

// Check message delivery status
if (event.data.ack === MessageAckStatus.READ) {
  console.log('Message was read!');
}

Available Enums​

WebhookEventType​

WebhookEventType.MESSAGE           // 'message'
WebhookEventType.MESSAGE_STATUS    // 'message-status'
WebhookEventType.QR_CODE           // 'qr-code'
WebhookEventType.CONTACT_CREATED   // 'contact-created'
WebhookEventType.CONTACT_UPDATED   // 'contact-updated'
WebhookEventType.CONTACT_DEDUPLICATED // 'contact-deduplicated'

InstanceStatus​

InstanceStatus.STOPPED             // 'stopped'
InstanceStatus.MANUALLY_STOPPED    // 'manually_stopped'
InstanceStatus.CONNECTING          // 'connecting'
InstanceStatus.PENDING_QR_CODE_SCAN // 'pending_qr_code_scan'
InstanceStatus.CONNECTED           // 'connected'
InstanceStatus.ERROR               // 'error'
InstanceStatus.CREATED             // 'created'
InstanceStatus.QR_TIMEOUT          // 'qr_timeout'
InstanceStatus.PAYMENT_PENDING     // 'payment_pending'

MessageAckStatus​

MessageAckStatus.PENDING    // 'pending'
MessageAckStatus.SENT       // 'sent'
MessageAckStatus.DELIVERED  // 'delivered'
MessageAckStatus.READ       // 'read'
MessageAckStatus.PLAYED     // 'played'

MessageType​

MessageType.TEXT      // 'text'
MessageType.IMAGE     // 'image'
MessageType.VIDEO     // 'video'
MessageType.AUDIO     // 'audio'
MessageType.DOCUMENT  // 'document'
MessageType.STICKER   // 'sticker'
MessageType.LOCATION  // 'location'
MessageType.CONTACT   // 'contact'
MessageType.POLL      // 'poll'
MessageType.REACTION  // 'reaction'

Webhook Handling​

Type Guards​

Use built-in type guards for type-safe webhook handling:

import {
  WebhookEvent,
  isMessageEvent,
  isMessageStatusEvent,
  isQRCodeEvent
} from '@zapyapi/sdk';

function handleWebhook(event: WebhookEvent) {
  if (isMessageEvent(event)) {
    // TypeScript knows event.data is MessageEventData
    console.log('From:', event.data.from.phone);
    console.log('Text:', event.data.text);
  }

  if (isMessageStatusEvent(event)) {
    // TypeScript knows event.data is MessageStatusEventData
    console.log('Status:', event.data.ack);
  }

  if (isQRCodeEvent(event)) {
    // TypeScript knows event.data is QRCodeEventData
    console.log('QR Code:', event.data.qrCode);
  }
}

Signature Verification​

Verify webhook signatures for security:

import { verifyWebhookSignature } from '@zapyapi/sdk';

app.post('/webhook', express.json(), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const isValid = verifyWebhookSignature(
    req.body,
    signature,
    process.env.WEBHOOK_SECRET
  );

  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Process webhook...
  res.status(200).send('OK');
});

Error Handling​

The SDK provides typed errors for better error handling:

import {
  ZapyClient,
  ZapyApiError,
  AuthenticationError,
  RateLimitError,
  InstanceNotFoundError,
  ValidationError
} from '@zapyapi/sdk';

try {
  await client.messages.sendText('my-instance', {
    to: '5511999999999',
    message: 'Hello!'
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limit exceeded, retry after:', error.retryAfter);
  } else if (error instanceof InstanceNotFoundError) {
    console.error('Instance not found');
  } else if (error instanceof ValidationError) {
    console.error('Invalid request:', error.message);
  } else if (error instanceof ZapyApiError) {
    console.error('API error:', error.statusCode, error.message);
  }
}

Utilities​

The SDK includes helpful utility functions:

import {
  normalizePhone,
  isValidPhone,
  isGroup,
  extractPhone
} from '@zapyapi/sdk';

// Normalize phone number to WhatsApp format
normalizePhone('11999999999'); // '5511999999999'
normalizePhone('+55 11 99999-9999'); // '5511999999999'

// Validate phone number
isValidPhone('5511999999999'); // true
isValidPhone('invalid'); // false

// Check if ID is a group
isGroup('[email protected]'); // false
isGroup('[email protected]'); // true

// Extract phone from WhatsApp ID
extractPhone('[email protected]'); // '5511999999999'

TypeScript Support​

The SDK is written in TypeScript and provides full type definitions:

import type {
  // Common types
  ZapyClientOptions,
  PaginationQuery,
  PaginatedResponse,

  // Instance types
  Instance,
  CreateInstanceOptions,
  QRCodeResponse,

  // Message types
  SendTextMessageOptions,
  SendImageMessageOptions,
  MessageResponse,

  // Webhook types
  WebhookEvent,
  MessageWebhookEvent,
  MessageEventData,
  ContactInfo
} from '@zapyapi/sdk';

ESM and CommonJS​

The SDK supports both ESM and CommonJS:

// ESM
import { ZapyClient } from '@zapyapi/sdk';

// CommonJS
const { ZapyClient } = require('@zapyapi/sdk');