إرسال SMS باستخدام JavaScript (Node.js): مكتبة API sms-node-client

مكتبة sms-node-client: إرسال SMS من Node.js

غالبًا ما تتطلب تطبيقات الويب الحديثة التكامل مع خدمات SMS لإرسال الإشعارات، تأكيدات التسجيل، أو الحملات التسويقية. توفر مكتبة sms-node-client واجهة بسيطة ومريحة للعمل مع بوابات SMS الشهيرة مباشرة من Node.js. وهي تجرد تعقيد طلبات HTTP والمصادقة، مما يسمح للمطور بالتركيز على منطق الأعمال.

في هذه المقالة، سنستعرض الإمكانيات الرئيسية للمكتبة: التثبيت، إعداد الاتصال بـ API، إرسال الرسائل الفردية والجماعية، بالإضافة إلى معالجة الأخطاء النموذجية.

التثبيت والاستيراد

يتم توزيع المكتبة عبر npm. للتثبيت، قم بتنفيذ الأمر التالي في جذر مشروعك:

npm install sms-node-client

بعد التثبيت، قم باستيراد المكتبة إلى ملف JavaScript الخاص بك:

const SMSClient = require('sms-node-client');

// أو باستخدام وحدات ES6 (إذا تم إعدادها)// import SMSClient from 'sms-node-client';

إعداد العميل

للعمل مع API، تحتاج إلى تهيئة كائن العميل عن طريق تمرير معلمات الاتصال: apiKey (مفتاح الوصول) و apiSecret (المفتاح السري). عادةً ما يتم توفير هذه البيانات من قبل مزود خدمة SMS الخاص بك.

const client = new SMSClient({  apiKey: 'مفتاح_api_الخاص_بك',  apiSecret: 'سر_api_الخاص_بك',  // اختياري: يمكن تحديد عنوان URL أساسي إذا كان المزود يستخدم نقطة نهاية غير قياسية  // baseUrl: 'https://custom-sms-gateway.com/api/v1'});

الطرق الرئيسية للمكتبة

توفر المكتبة ثلاث طرق رئيسية لإرسال الرسائل:

• sendSMS(phone, message, options?) — إرسال رسالة SMS واحدة إلى رقم واحد.
• sendBulkSMS(messages, options?) — إرسال جماعي إلى عدة أرقام.
• getStatus(messageId) — التحقق من حالة التسليم باستخدام معرف الرسالة.

مثال: إرسال رسالة SMS واحدة

السيناريو الأبسط هو إرسال رسالة إلى رقم واحد. تقوم الطريقة بإرجاع Promise، لذلك من المناسب استخدام async/await.

async function sendSingleSMS() {  try {    const result = await client.sendSMS(      '+71234567890',            // رقم المستلم بالتنسيق الدولي      'مرحباً! هذه رسالة اختبارية من Node.js.', // نص الرسالة      { sender: 'MyApp' }       // اختياري: اسم المرسل (يجب أن يكون مسجلاً لدى المزود)    );

    console.log('تم إرسال SMS بنجاح:', result);    // result.messageId - معرف فريد للرسالة لتتبع الحالة  } catch (error) {    console.error('خطأ في إرسال SMS:', error.message);  }}

sendSingleSMS();

مثال: إرسال جماعي

لإرسال نفس النص إلى عدة أرقام، استخدم طريقة sendBulkSMS. تقبل مصفوفة من الكائنات التي تحتوي على الأرقام.

async function sendBulk() {  const recipients = [    { phone: '+71234567890' },    { phone: '+70987654321' },    { phone: '+70123456789' }  ];

  try {    const result = await client.sendBulkSMS(recipients, {      message: 'عزيزي العميل! طلبك جاهز للاستلام.',      sender: 'ShopBot'    });

    console.log(`تم إرسال ${result.sentCount} رسالة`);    // result.messages - مصفوفة تحتوي على تفاصيل كل رقم  } catch (error) {    console.error('خطأ في الإرسال الجماعي:', error);  }}

sendBulk();

التحقق من حالة التسليم

بعد الإرسال، يمكنك التحقق مما إذا كانت الرسالة قد وصلت إلى المستلم. للقيام بذلك، استخدم messageId الذي تم الحصول عليه عند الإرسال.

async function checkStatus(messageId) {  try {    const status = await client.getStatus(messageId);    console.log('حالة الرسالة:', status);    // status.s