Twilio لجافا سكريبت (Node.js): دليل شامل مع أمثلة

1. ما هي Twilio ولماذا تحتاجها؟

Twilio هي منصة اتصالات سحابية (CPaaS) توفر للمطورين واجهات برمجية (API) لدمج وظائف المكالمات الصوتية، والرسائل النصية (SMS)، والوسائط المتعددة (MMS)، والفيديو، والتحقق بخطوتين (2FA) في تطبيقات الويب والجوال. مكتبة twilio الخاصة بـ Node.js هي الـ SDK الرسمي الذي يبسّط التعقيدات المرتبطة بطلبات HTTP المباشرة لواجهة REST API الخاصة بـ Twilio، مما يوفر واجهة سهلة وآمنة للتعامل مع جميع خدمات المنصة.

لماذا تحتاجها؟ في عالم اليوم، أصبحت الاتصالات جزءًا لا يتجزأ من أي عمل تجاري. تتيح لك Twilio إضافة ميزات مثل إرسال إشعارات SMS، وإجراء مكالمات آلية (لتأكيد الطلبات أو تذكير بالمواعيد)، وإنشاء قوائم صوتية تفاعلية (IVR)، وغيرها الكثير، بسرعة وبدون تكاليف بنية تحتية ضخمة. بدلاً من بناء وصيانة بنية اتصالات خاصة بك، تحصل على شبكة عالمية من مزودي الخدمة عبر واجهة برمجية بسيطة.

مكتبة Node.js تحظى بشعبية خاصة بفضل الطبيعة غير المتزامنة (Asynchronous) للغة JavaScript وانتشار Node.js في تطوير الواجهات الخلفية. تدعم المكتبة Promises و async/await، مما يجعل الكود نظيفًا وسهل القراءة. يتولى الـ SDK معالجة إعادة المحاولة تلقائيًا عند حدوث أخطاء في الشبكة، ويدير المصادقة عبر Account SID و Auth Token، ويوفر أنواعًا مدمجة لـ TypeScript، مما يبسط عملية التطوير وتصحيح الأخطاء بشكل كبير.

2. التثبيت

يتم تثبيت المكتبة عبر مدير الحزم npm. تأكد من تثبيت Node.js الإصدار 14 أو أحدث.

npm install twilio

لاستخدام TypeScript، لا تحتاج لتثبيت أنواع إضافية، حيث تحتوي المكتبة على تعريفات أنواع مدمجة.

npm install twilio @types/twilio

بعد التثبيت، يمكنك استيراد المكتبة إلى مشروعك:

const twilio = require('twilio'); // CommonJS
// أو
import twilio from 'twilio'; // ES Modules

3. البداية السريعة — مثال عملي بسيط

قبل البدء، ستحتاج إلى بيانات الاعتماد من لوحة تحكم Twilio: Account SID و Auth Token. كما يجب عليك شراء رقم هاتف من لوحة تحكم Twilio.

// استيراد المكتبة
const twilio = require('twilio');

// بيانات الاعتماد من لوحة تحكم Twilio
const accountSid = 'ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX'; // استبدل بـ SID الخاص بك
const authToken = 'your_auth_token'; // استبدل بـ Token الخاص بك

// إنشاء كائن العميل
const client = twilio(accountSid, authToken);

// إرسال رسالة SMS
client.messages
  .create({
    body: 'مرحباً بالعالم! هذه رسالة اختبار من Twilio.',
    from: '+1234567890', // رقم Twilio الخاص بك
    to: '+0987654321'    // رقم المستلم
  })
  .then(message => console.log('تم إرسال الرسالة. SID:', message.sid))
  .catch(error => console.error('خطأ:', error));

هذا المثال البسيط يرسل رسالة SMS. بعد الإرسال الناجح، سيتم عرض المعرف الفريد للرسالة (SID) في وحدة التحكم.

4. أهم الطرق/الدوال/الفئات

4.1. client.messages.create()

التوقيع: client.messages.create(params: MessageCreateParams): Promise<MessageInstance>

الوصف: إرسال رسالة SMS أو MMS. تشمل المعاملات body (النص)، from (رقم المرسل)، to (رقم المستلم)، بالإضافة إلى mediaUrl اختياري (لـ MMS) و statusCallback.

client.messages
  .create({
    body: 'رمز التحقق الخاص بك: 1234',
    from: '+1234567890',