veevotech-whatsapp

A lightweight, zero-dependency Node.js client wrapper for Veevo Tech's WhatsApp Business API framework. Engineered entirely on the native HTTP fetch API for compatibility with modern environments like Node.js (18+), Express, and Next.js.

Core Features

• Zero Dependencies: Built natively to limit bundle overhead.
• Flexible Message Mapping: Supports standard text, template variables, files, and rich interaction schemas.
• Automated Form Boundaries: Native multi-part handling handles media uploads cleanly.
• Account Analytics: Run live usage metrics and real-time wallet tracing directly from the wrapper.

Installation

npm install veevotech-whatsapp

Initialization

Add your custom security authentication hash variable to your project profile (.env):

VEEVOTECH_WHATSAPP_HASH="your_unique_whatsapp_hash_here"

Initialize the interface wrapper inside your service pipeline:

import { VeevoTechWhatsApp } from 'veevotech-whatsapp';

const waClient = new VeevoTechWhatsApp({
  hash: process.env.VEEVOTECH_WHATSAPP_HASH
});

Content Message Layouts & Return Responses

1. Send Text Messages

const result = await waClient.sendMessage({
  to: '923001234567',
  type: 'text',
  text: { body: 'Hello, this is a clean text message payload.' }
});

Success Response JSON Structure

{
  "status": "SUCCESS",
  "data": {
    "STATUS": "SUCCESSFUL",
    "MESSAGE_ID": "669536ec23850d201ef0aeab",
    "ERROR_FILTER": "",
    "ERROR_CODE": "",
    "ERROR_DESCRIPTION": ""
  }
}

2. Send Business Templates

const result = await waClient.sendMessage({
  to: '923001234567',
  type: 'template',
  template_id: 42,
  header_variables: ['John'],
  body_variables: ['var1', 'var2'],
  media_url: [],
  priority: 1
});

3. Media Uploads & Message Piping

import fs from 'fs';

const rawBuffer = fs.readFileSync('./invoice.pdf');
const uploadResult = await waClient.uploadMedia(rawBuffer, 'invoice.pdf');

if (uploadResult.status === 'SUCCESS') {
  const fileId = uploadResult.data.FILE_ID;

  await waClient.sendMessage({
    to: '923001234567',
    type: 'document',
    document: {
      link: fileId,
      filename: 'invoice.pdf',
      caption: 'Your monthly statement overview'
    }
  });
}

Media Upload Success Response

{
  "status": "SUCCESS",
  "data": {
    "STATUS": "SUCCESSFUL",
    "FILE_ID": "933559029115799",
    "FILE_URL": "",
    "ERROR_CODE": "",
    "ERROR_DESCRIPTION": ""
  }
}

Other Media Types

• Image: type: "image", image: { link: fileId, caption: "Hi!" }
• Audio: type: "audio", audio: { link: fileId }
• Video: type: "video", video: { link: fileId, caption: "Watch this" }

Interactive Components

Location Request

await waClient.sendMessage({
  to: '923001234567',
  type: 'interactive',
  interactive: {
    type: 'location_request_message',
    body: { text: 'Please share your dynamic shipping dropoff address.' },
    action: { name: 'send_location' }
  }
});

Location Message

await waClient.sendMessage({
  to: '923001234567',
  type: 'location',
  location: {
    latitude: '31.5204',
    longitude: '74.3587',
    name: 'Veevo Tech HQ',
    address: 'Lahore, Pakistan'
  }
});

General Button Messages

await waClient.sendMessage({
  to: '923001234567',
  type: 'interactive',
  interactive: {
    type: 'button',
    header: { type: 'text', text: 'Confirm Actions' },
    body: { text: 'Would you like to authorize this processing order call?' },
    footer: { text: 'Select option below' },
    action: {
      buttons: [
        { type: 'reply', reply: { id: 'btn_yes', title: 'Yes, Proceed' } },
        { type: 'reply', reply: { id: 'btn_no', title: 'Cancel Order' } }
      ]
    }
  }
});

Call to Action (CTA) URL

await waClient.sendMessage({
  to: '923001234567',
  type: 'interactive',
  interactive: {
    type: 'cta_url',
    header: { type: 'text', text: 'Tracking Framework Portal' },
    body: { text: 'Your delivery truck is in transit. View progress updates via link.' },
    footer: { text: 'Ecom Nest Logistics' },
    action: {
      name: 'cta_url',
      parameters: {
        display_text: 'Open Maps Route',
        url: 'https://example.com/track/route'
      }
    }
  }
});

Metric Analytics & Wallet Reporting

Get Yearly Analytics

const report = await waClient.getYearlyAnalytics();

Get Credit History

const history = await waClient.getCreditHistory();

Error Pipeline Interception

Always map backend exception checks to error.filter.

Expected Error Sample

{
  "status": "ERROR",
  "error": {
    "filter": "NO_OPEN_CONV",
    "description": "Failed to send your message, no user-initiated conversation found with this contact.",
    "code": "VTWE-144773755"
  }
}

Author

Nouman Qamar
Digital Marketing Professional & Full-Stack Engineer.