veevotech-sms

A lightweight, zero-dependency Node.js client wrapper for Veevo Tech's CPaaS v3.0 SMS and Voice OTP platforms. Built entirely on the native HTTP fetch API, making it fully compatible with modern backend environments like Node.js (18+), Express, and Next.js (Edge and Server runtimes).

Features

• Zero Dependencies: Built on native fetch (no heavy Axios layers).
• Standard SMS: Send high-speed text transmissions globally using international formatting.
• Voice OTP: Route automated text-to-speech verification calls seamlessly via the VT-vOTP masking network.
• Stable Error Handling: Exposes predictable error.filter states to decouple your codebase logic from shifting platform error logs.

Installation

npm install veevotech-sms

Initialization

Add your 45-character API key parameter inside your environmental config variables (.env):

VEEVOTECH_SMS_API_KEY="your_unique_api_key_here"

Initialize the client in your application logic:

import { VeevoTechSms } from 'veevotech-sms';

const smsClient = new VeevoTechSms({
  apiKey: process.env.VEEVOTECH_SMS_API_KEY
});

Usage & JSON Responses

1. Send Standard SMS Message

const result = await smsClient.sendSMS({
  to: '+923001234567',
  message: 'Hello, this is a test SMS message from Veevo Tech.',
  senderId: 'Default'
});

if (result.status === 'ERROR') {
  console.error('Failed:', result.error.description);
} else {
  console.log('Success:', result.data);
}

Expected Success JSON Output

{
  "status": "SUCCESS",
  "data": {
    "STATUS": "SUCCESSFUL",
    "MESSAGE_ID": "4d6a6b31",
    "COUNTRY_SUPPORTED": "TRUE",
    "COUNTRY_CODE": 92,
    "COUNTRY_ISO": "PK",
    "NETWORK_NAME": "Mobilink-PK",
    "RECEIVER_NUMBER": "+923001234567",
    "ERROR_FILTER": "",
    "ERROR_CODE": "",
    "ERROR_DESCRIPTION": "",
    "CHARGED_BALANCE": 0
  }
}

2. Send Automated Voice OTP (Text-To-Speech Call)

const result = await smsClient.sendVoiceOTP({
  to: '+923001234567',
  message: 'Your verification code is 5 2 9 1.'
});

if (result.status === 'ERROR') {
  console.error('Failed:', result.error.description);
} else {
  console.log('Success:', result.data);
}

Expected Success JSON Output

{
  "status": "SUCCESS",
  "data": {
    "STATUS": "SUCCESSFUL",
    "MESSAGE_ID": "4e7a45354e7a6735",
    "COUNTRY_SUPPORTED": "TRUE",
    "COUNTRY_CODE": 92,
    "COUNTRY_ISO": "PK",
    "NETWORK_NAME": "Mobilink-PK",
    "RECEIVER_NUMBER": "+923001234567",
    "ERROR_FILTER": "",
    "ERROR_CODE": "",
    "ERROR_DESCRIPTION": "",
    "CHARGED_BALANCE": 0
  }
}

Error Handling Pattern

The wrapper standardizes validation logic around the stable error.filter value. Do not map branching behaviors to error.code.

Expected Error JSON Output

{
  "status": "ERROR",
  "error": {
    "filter": "INSUFFICIENT_BALANCE",
    "description": "Account balance is too low.",
    "code": "VTWE-141966952",
    "original": {
      "STATUS": "ERROR",
      "ERROR_FILTER": "INSUFFICIENT_BALANCE",
      "ERROR_CODE": "VTWE-141966952",
      "ERROR_DESCRIPTION": "Account balance is too low.",
      "MESSAGE_ID": ""
    }
  }
}

Application-Level Error Handling

const result = await smsClient.sendSMS({
  to: '+923001234567',
  message: 'Alert Payload'
});

if (result.status === 'ERROR') {
  switch (result.error.filter) {
    case 'INSUFFICIENT_BALANCE':
      console.error('Critical Alert: Top up your Veevo Tech wallet immediately.');
      break;
    case 'INVALID_NUMBER':
      console.warn('The requested user phone number is formatted incorrectly.');
      break;
    default:
      console.error(`General System Error: ${result.error.description}`);
  }
}

Reference Stable Error Filters

| Error Filter | Description | |---|---| | INVALID_API_KEY | Incorrect, un-whitelisted, or missing API key config rules. | | INSUFFICIENT_BALANCE | Wallet token limits are too low to dispatch messages. | | INVALID_NUMBER | Target address string doesn't follow international format templates. | | CONTENT_TOO_LONG | Message body exceeds 800 tokens. | | HEADER_ID_NOT_FOUND | Requested senderId masking tag not approved. |

Author

Nouman Qamar
Digital Marketing Professional & Full-Stack Engineer.