Vesal

A modern TypeScript/JavaScript client for the Armaghan Vesal SMS API.

Features

• 🚀 Modern ESM/CommonJS support
• 📘 Full TypeScript support with type definitions
• 🔄 Promise-based API
• ✨ Simple and intuitive interface
• 🛡️ Built-in error handling
• 📱 Send SMS (one-to-many and many-to-many)
• 📊 Check message status
• 📥 Receive messages
• 👤 Account management

Installation

npm install vesal

yarn add vesal

pnpm add vesal

Quick Start

import { Vesal } from 'vesal';

// Initialize the client
const client = new Vesal(
  'your-username',
  'your-password',
  'your-sender-number'
);

// Send a simple SMS
const result = await client.Send({
  recipients: '09123456789',
  messages: 'Hello, World!'
});

console.log(`Sent ${result.count.success} messages successfully`);

API Reference

Constructor

new Vesal(username: string, password: string, from: string)

Creates a new Vesal client instance.

Parameters:

• username - Your Vesal API username
• password - Your Vesal API password
• from - Default sender number

Example:

const client = new Vesal('myusername', 'mypassword', '50002710000000');

Send()

async Send({
  recipients,
  messages,
  from
}: {
  recipients: string | string[];
  messages: string | string[];
  from?: string | string[];
}): Promise<IVesalResponse_Send_WithCount>

Sends SMS messages to one or multiple recipients.

Parameters:

• recipients - Phone number(s) to send to (e.g., '09123456789' or ['09123456789', '09987654321'])
• messages - Message content(s) to send
• from - (Optional) Sender number(s), defaults to the number set in constructor

Return Value:

{
  references: (number | string)[],  // Reference IDs for sent messages
  count: {
    success: number,  // Number of successfully sent messages
    fail: number      // Number of failed messages
  },
  errorModel: {
    errorCode: number,
    timestamp: string | number | null
  }
}

Send Methods

One-to-Many (Same message to multiple recipients):

await client.Send({
  recipients: ['09123456789', '09987654321'],
  messages: 'Hello everyone!'
});

Many-to-Many (Different messages to different recipients):

await client.Send({
  recipients: ['09123456789', '09987654321'],
  messages: ['Hello John!', 'Hello Jane!']
});

Single message with custom sender:

await client.Send({
  recipients: '09123456789',
  messages: 'Your verification code is 1234',
  from: '50002710000001'
});

GetMessageStatus()

async GetMessageStatus(referencesIds: number[]): Promise<IVesalResponse_MessageState>

Gets the delivery status of sent messages.

Parameters:

• referencesIds - Array of reference IDs returned from Send()

Return Value:

{
  states: Array<{
    id: number,      // Reference ID
    state: number    // Status code (see Message States below)
  }>,
  errorModel: {
    errorCode: number,
    timestamp: string | number | null
  }
}

Example:

const sendResult = await client.Send({
  recipients: '09123456789',
  messages: 'Test message'
});

// Wait a bit for delivery
await new Promise(resolve => setTimeout(resolve, 5000));

const statusResult = await client.GetMessageStatus(sendResult.references);
console.log(statusResult.states);
// Output: [{ id: 123456, state: 2 }]

GetReceivedMessages()

async GetReceivedMessages(): Promise<IVesalResponse_ReceivedMessages>

Retrieves all received messages.

Return Value:

{
  messageModels: Array<{
    originator: string,    // Sender's phone number
    destination: string,   // Your receiving number
    content: string        // Message content
  }>,
  errorModel: {
    errorCode: number,
    timestamp: string | number | null
  }
}

Example:

const received = await client.GetReceivedMessages();
received.messageModels.forEach(msg => {
  console.log(`From: ${msg.originator}`);
  console.log(`To: ${msg.destination}`);
  console.log(`Message: ${msg.content}`);
});

GetReceivedMessagesCount()

async GetReceivedMessagesCount(): Promise<IVesalResponse_ReceivedMessagesCount>

Gets the count of received messages.

Return Value:

{
  count: number,
  errorModel: {
    errorCode: number,
    timestamp: string | number | null
  }
}

Example:

const result = await client.GetReceivedMessagesCount();
console.log(`You have ${result.count} new messages`);

GetUserInfo()

async GetUserInfo(): Promise<IVesalResponse_UserInfo>

Retrieves user account information including credit balance, active numbers, and account status.

Return Value:

{
  user: {
    credit: number,              // Account credit balance
    numbers: string[],           // Your sender numbers
    username: string,
    active: boolean,
    expirationDate: string,
    // ... other account details
  },
  errorModel: {
    errorCode: number,
    timestamp: string | number | null
  }
}

Example:

const userInfo = await client.GetUserInfo();
console.log(`Credit: ${userInfo.user.credit}`);
console.log(`Active: ${userInfo.user.active}`);
console.log(`Numbers: ${userInfo.user.numbers.join(', ')}`);
console.log(`Expires: ${userInfo.user.expirationDate}`);

Error Handling

The package includes a custom VesalError class for API errors:

import { Vesal, VesalError } from 'vesal';

try {
  await client.Send({
    recipients: '09123456789',
    messages: 'Test'
  });
} catch (error) {
  if (error instanceof VesalError) {
    console.error(`Vesal Error ${error.status}: ${error.message}`);
  } else {
    console.error('Unexpected error:', error);
  }
}

Common Error Codes

| Code | Description (English) | توضیحات (فارسی) | |------|----------------------|------------------| | 0 | Success | عملیات با موفقیت انجام شد | | -100 | Reference ID not found | refrenceId مورد نظر یافت نشد | | -101 | Authentication failed | احراز هویت کاربر موفقیت آمیز نبود | | -102 | Username not found | نام کاربری یافت نشد | | -103 | Invalid originator number | شماره originator اشتباه یا در بازه شماره های کاربر نیست | | -104 | Insufficient credit | اعتبار کم است | | -105 | Invalid request format | فرمت درخواست اشتباه است | | -107 | Invalid recipient number | شماره گیرنده پیامک اشتباه است | | -109 | Account expired | تاریخ انقضای حساب کاربری فرارسیده است | | -110 | IP not allowed | درخواست از ip مجاز کاربر ارسال نشده است | | -111 | Number blacklisted | شماره گیرنده در بلک لیست قرار دارد | | -112 | Account inactive | حساب مشتری فعال نیست | | -119 | Access denied | کاربر به سرویس مورد نظر دسترسی ندارد | | -120 | No valid recipients | پیام ارسال شده دارای هیچ شماره معتبری نیست | | -137 | Forbidden content | پیام نباید حاوی کلمات غیرمجاز می باشد |

Get error description:

import { GetStatusText } from 'vesal';

const errorMessage = GetStatusText(-104);
console.log(errorMessage); // "اعتبار کم است"

Message States

After sending a message, you can check its delivery status:

| State | Description (English) | توضیحات (فارسی) | |-------|----------------------|------------------| | 0 | In queue | پیامک در صف ارسال قرار دارد | | 1 | Sent to operator | ارسال شده | | 2 | Delivered | پیامک به موبایل گیرنده تحویل شده است | | 3 | Not delivered | پیامک به موبایل گیرنده تحویل نشده است | | 4 | Unknown status | وضعیت نامشخص | | 5 | Received by system | پیامک توسط وب سرویس به شرکت ارمغان راه طلایی رسیده است | | 6 | Cancelled by operator | پیام از سمت اپراتور لغو شده است | | 7 | Expired by operator | پیام از سمت اپراتور منقضی شده است | | 8 | Rejected by operator | پیام از سمت اپراتور reject شده است |

Access state descriptions:

import { messageStates } from 'vesal';

console.log(messageStates[2]); // "پیامک به موبایل گیرنده تحویل شده است"

Complete Example

import { Vesal, VesalError, messageStates } from 'vesal';

async function main() {
  // Initialize client
  const client = new Vesal(
    'your-username',
    'your-password',
    '50002710000000'
  );

  try {
    // Check account info
    const userInfo = await client.GetUserInfo();
    console.log(`Credit: ${userInfo.user.credit}`);
    console.log(`Active: ${userInfo.user.active}`);

    // Send SMS
    const sendResult = await client.Send({
      recipients: ['09123456789', '09987654321'],
      messages: 'Hello from Vesal!'
    });

    console.log(`Successfully sent: ${sendResult.count.success}`);
    console.log(`Failed: ${sendResult.count.fail}`);

    // Check status after a delay
    await new Promise(resolve => setTimeout(resolve, 10000));

    const validRefs = sendResult.references.filter(
      ref => typeof ref === 'number'
    ) as number[];

    if (validRefs.length > 0) {
      const status = await client.GetMessageStatus(validRefs);
      status.states.forEach(state => {
        console.log(
          `Message ${state.id}: ${messageStates[state.state]}`
        );
      });
    }

    // Check received messages
    const received = await client.GetReceivedMessages();
    console.log(`Received ${received.messageModels.length} messages`);

  } catch (error) {
    if (error instanceof VesalError) {
      console.error(`Error ${error.status}: ${error.message}`);
    } else {
      console.error('Unexpected error:', error);
    }
  }
}

main();

TypeScript Support

The package includes full TypeScript definitions. All types are automatically available:

import type {
  IVesalResponse_Send_WithCount,
  IVesalResponse_MessageState,
  IVesalResponse_ReceivedMessages,
  IVesalResponse_ReceivedMessagesCount,
  IVesalResponse_UserInfo
} from 'vesal';

You can also import the source TypeScript directly:

import { Vesal } from 'vesal/ts';

API Endpoint

The package connects to: http://vesal.armaghan.net:8080/rest

License

MIT © Shahab Movahhedi

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

• Issues: GitHub Issues
• Author: Shahab Movahhedi
• Email: [email protected]

Links

• npm Package
• GitHub Repository
• Author's Website