Magfa SMS API Client

A modern, fully-typed JS/TS/ESM/Node.js client for the Magfa SMS API v2.

Features

• 🚀 Modern: Built with TypeScript and modern JavaScript
• 📦 Multiple Formats: CommonJS, ES Modules, and UMD builds
• 🔒 Fully Typed: Complete TypeScript definitions included
• ⚡ Promise-based: Async/await support out of the box
• 🛡️ Error Handling: Comprehensive error messages in Persian
• 🔄 Multiple Encodings: Support for Persian, English, 8-bit, and Binary

Installation

npm install magfa-api

or

yarn add magfa-api

Quick Start

import Magfa from 'magfa-api';

const magfa = new Magfa(
  'username',    // Your Magfa username
  'password',    // Your Magfa password
  'domain',      // Your domain
  '3000xxxxx'    // Your sender number
);

// Send a simple SMS
const result = await magfa.Send({
  recipients: '09123456789',
  messages: 'سلام، این یک پیام تستی است'
});

console.log(result);

API Reference

Constructor

new Magfa(username: string, password: string, domain: string, from: string)

Creates a new Magfa client instance.

Parameters:

• username (string): Your Magfa account username
• password (string): Your Magfa account password
• domain (string): Your Magfa domain
• from (string): Default sender number for outgoing messages

Example:

const magfa = new Magfa('myuser', 'mypass', 'mydomain', '3000xxxxx');

Methods

Send

Send one or multiple SMS messages.

Send(options: {
  recipients: string | string[];
  messages: string | string[];
  encodings?: Encoding | Encoding[];
  uids?: number[];
  udhs?: string[];
}): Promise<ISendResponseWithCount>

Parameters:

• recipients (string | string[]): Phone number(s) to send to (e.g., '09123456789' or ['09123456789', '09187654321'])
• messages (string | string[]): Message text(s) to send
• encodings (optional): Encoding type(s) for messages (default: Auto-detect)
• uids (optional): Unique identifiers for tracking messages
• udhs (optional): User Data Header for advanced messaging

Returns:

{
  status: number;
  messages: ISentMessage[];
  count: {
    success: number;
    fail: number;
  };
}

Examples:

Send a single message:

const result = await magfa.Send({
  recipients: '09123456789',
  messages: 'Hello World'
});

Send multiple messages to multiple recipients:

const result = await magfa.Send({
  recipients: ['09123456789', '09187654321'],
  messages: ['Message for first recipient', 'Message for second recipient']
});

Send the same message to multiple recipients:

const result = await magfa.Send({
  recipients: ['09123456789', '09187654321', '09351234567'],
  messages: 'This message goes to everyone'
});

Send with specific encoding:

import { Encoding } from 'magfa-api';

const result = await magfa.Send({
  recipients: '09123456789',
  messages: 'سلام دنیا',
  encodings: Encoding.Persian
});

Send with unique IDs for tracking:

const result = await magfa.Send({
  recipients: ['09123456789', '09187654321'],
  messages: ['Message 1', 'Message 2'],
  uids: [1001, 1002]
});

Statuses

Get delivery status of sent messages.

Statuses(mids: number[]): Promise<IMagfaResponse_Statuses>

Parameters:

• mids (number[]): Array of message IDs to check status for

Returns:

{
  status: number;
  dlrs: Array<{
    mid: number;        // Message ID
    status: number;     // Delivery status code
    date: string;       // Date in 'yyyy-mm-dd hh:mm:ss' format
  }>;
}

Example:

const statuses = await magfa.Statuses([123456, 123457, 123458]);

statuses.dlrs.forEach(dlr => {
  console.log(`Message ${dlr.mid}: Status ${dlr.status} at ${dlr.date}`);
});

Status Codes:

• -1: ID not found (invalid ID or more than 24 hours passed)
• 0: No status received yet
• 1: Delivered to phone
• 2: Not delivered to phone
• 8: Delivered to operator
• 16: Not delivered to operator

Mid

Get message ID by unique identifier.

Mid(uid: number): Promise<IMagfaResponse_Mid>

Parameters:

• uid (number): The unique identifier you provided when sending the message

Returns:

{
  status: number;
  mid: number | undefined;  // Message ID
}

Example:

// First send with UID
await magfa.Send({
  recipients: '09123456789',
  messages: 'Test message',
  uids: [1001]
});

// Later retrieve the message ID
const result = await magfa.Mid(1001);
console.log(`Message ID: ${result.mid}`);

Balance

Check your account balance.

Balance(): Promise<IMagfaResponse_Balance>

Returns:

{
  status: number;
  balance: number | null;  // Balance in Rials
}

Example:

const result = await magfa.Balance();
console.log(`Current balance: ${result.balance} Rials`);

ReceivedMessages

Retrieve received messages.

ReceivedMessages(count?: number): Promise<IMagfaResponse_ReceivedMessages>

Parameters:

• count (number, optional): Number of messages to retrieve (default: 100)

Returns:

{
  status: number;
  messages: Array<{
    body: string;              // Message content
    senderNumber: string;      // Sender phone number
    recipientNumber: string;   // Recipient phone number (your number)
    date: string;              // Date in 'yyyy-mm-dd hh:mm:ss' format
  }>;
}

Example:

// Get last 50 received messages
const result = await magfa.ReceivedMessages(50);

result.messages.forEach(msg => {
  console.log(`From ${msg.senderNumber}: ${msg.body}`);
});

Types and Interfaces

Encoding

Enum for message encoding types:

enum Encoding {
  Auto = 0,      // Auto-detect (default)
  Persian = 2,   // Persian/Farsi
  EightBit = 5,  // 8-bit
  Binary = 6     // Binary
}

ISentMessage

Information about a sent message:

interface ISentMessage {
  status: number;        // Status code (0 = success)
  id: number;            // Unique message ID
  userId: number;        // User ID
  parts: number;         // Number of message parts
  tariff: number;        // Message cost
  alphabet: "DEFAULT" | "UCS2";  // Encoding type
  recipient: string;     // Recipient phone number
  message?: string;      // Status message (in Persian)
}

ISendResponseWithCount

Response from Send method:

interface ISendResponseWithCount {
  status: number;
  messages: ISentMessage[];
  count: {
    success: number;     // Number of successfully sent messages
    fail: number;        // Number of failed messages
  };
}

Error Handling

The package includes a custom MagfaError class that provides detailed error messages in Persian:

import Magfa, { MagfaError } from 'magfa-api';

try {
  const result = await magfa.Send({
    recipients: '09123456789',
    messages: 'Test message'
  });
} catch (error) {
  if (error instanceof MagfaError) {
    console.error(`Magfa Error [${error.status}]: ${error.message}`);
  } else {
    console.error('Unknown error:', error);
  }
}

Common Error Codes

| Code | Description (Persian) | |------|----------------------| | 1 | شماره گیرنده نادرست است | | 2 | شماره فرستنده نادرست است | | 14 | مانده اعتبار ریالی مورد نیاز برای ارسال پیامک کافی نیست | | 16 | حساب غیرفعال است | | 17 | حساب منقضی شده است | | 18 | نام کاربری و یا کلمه عبور نامعتبر است | | 20 | شماره فرستنده به حساب تعلق ندارد |

See full error codes list

Advanced Usage

Batch Sending with Progress Tracking

async function sendBatch(recipients: string[], message: string) {
  const batchSize = 100;
  const results = [];

  for (let i = 0; i < recipients.length; i += batchSize) {
    const batch = recipients.slice(i, i + batchSize);
    const result = await magfa.Send({
      recipients: batch,
      messages: message
    });

    results.push(result);
    console.log(`Batch ${i / batchSize + 1}: ${result.count.success} sent, ${result.count.fail} failed`);
  }

  return results;
}

Custom Sender for Individual Messages

// While the constructor sets a default sender,
// all messages will use this sender.
// To use different senders, create multiple Magfa instances.

const magfa1 = new Magfa('user', 'pass', 'domain', '3000111111');
const magfa2 = new Magfa('user', 'pass', 'domain', '3000222222');

await magfa1.Send({ recipients: '09123456789', messages: 'From first number' });
await magfa2.Send({ recipients: '09187654321', messages: 'From second number' });

Polling Message Status

async function waitForDelivery(mid: number, maxAttempts = 10): Promise<number> {
  for (let i = 0; i < maxAttempts; i++) {
    const result = await magfa.Statuses([mid]);
    const status = result.dlrs[0]?.status;

    if (status === 1) {
      console.log('Message delivered!');
      return status;
    } else if (status === 2 || status === 16) {
      console.log('Message delivery failed');
      return status;
    }

    // Wait 5 seconds before next check
    await new Promise(resolve => setTimeout(resolve, 5000));
  }

  console.log('Delivery status unknown after maximum attempts');
  return 0;
}

// Usage
const result = await magfa.Send({
  recipients: '09123456789',
  messages: 'Test'
});
const mid = result.messages[0].id;
await waitForDelivery(mid);

Error Codes Reference

Send Errors (1-31, 101-110)

| Code | Description | |------|-------------| | 1 | شماره گیرنده نادرست است | | 2 | شماره فرستنده نادرست است | | 3 | پارامتر encoding نامعتبر است | | 4 | پارامتر mclass نامعتبر است | | 6 | پارامتر UDH نامعتبر است | | 13 | محتویات پیامک خالی است | | 14 | مانده اعتبار کافی نیست | | 15 | سرور مشغول است - ارسال مجدد | | 16 | حساب غیرفعال است | | 17 | حساب منقضی شده است | | 18 | نام کاربری یا کلمه عبور نامعتبر است | | 19 | درخواست معتبر نیست | | 20 | شماره فرستنده به حساب تعلق ندارد | | 22 | سرویس فعال نشده است | | 23 | امکان پردازش وجود ندارد - تلاش مجدد | | 24 | شناسه پیامک معتبر نیست | | 25 | نام متد معتبر نیست | | 27 | گیرنده در لیست سیاه است | | 28 | گیرنده مسدود است | | 29 | IP اجازه دسترسی ندارد | | 30 | تعداد بخش‌ها بیش از حد مجاز است | | 31 | داده‌های ناکافی | | 101 | عدم تطابق طول آرایه messageBodies | | 102 | عدم تطابق طول آرایه messageClass | | 103 | عدم تطابق طول آرایه senderNumbers | | 104 | عدم تطابق طول آرایه udhs | | 105 | عدم تطابق طول آرایه priorities | | 106 | آرایه گیرندگان خالی است | | 107 | طول آرایه گیرندگان بیش از حد مجاز | | 108 | آرایه فرستندگان خالی است | | 109 | عدم تطابق طول آرایه encoding | | 110 | عدم تطابق طول آرایه checkingMessageIds |

Delivery Status Codes

| Code | Description | |------|-------------| | -1 | شناسه موجود نیست | | 0 | وضعیتی دریافت نشده | | 1 | رسیده به گوشی | | 2 | نرسیده به گوشی | | 8 | رسیده به مخابرات | | 16 | نرسیده به مخابرات |

Utility Functions

GetStatusText

Get human-readable status message:

import { GetStatusText } from 'magfa-api';

const statusText = GetStatusText(18);
console.log(statusText); // "نام کاربری و یا کلمه عبور نامعتبر است"

TypeScript Support

This package is written in TypeScript and includes full type definitions. All types are exported and can be imported:

import Magfa, {
  MagfaError,
  Encoding,
  ISentMessage,
  ISendResponseWithCount,
  GetStatusText,
  magfaErrors,
  messageStatuses
} from 'magfa-api';

You can also import types from the TypeScript source directly:

import type { ISentMessage } from 'magfa-api/ts';

Browser Support

While this package is primarily designed for Node.js, it uses the standard fetch API which is available in modern browsers. However, note that:

1. Browser security policies may block direct API calls (CORS)
2. Credentials would be exposed in client-side code
3. It's recommended to use this package on the server-side only

License

MIT © Shahab Movahhedi

Resources

• Official Magfa API Documentation
• GitHub Repository
• NPM Package

Contributing

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

Author

Shahab Movahhedi

• Website: shmovahhedi.com
• Email: [email protected]

Support

If you find this package helpful, please consider:

• ⭐ Starring the GitHub repository
• 🐛 Reporting bugs or suggesting features via GitHub Issues
• 📖 Improving documentation