Node.js

ربط واتساب مع Node.js

مكتبة wasaas تُغلّف واجهة Wasaas البرمجية حتى ترسل رسائل واتساب من أي خدمة Node.js بدون كتابة استدعاءات HTTP يدويًا. تأتي بأنواع TypeScript، بدون أي اعتماديات تشغيل، وتعمل على رقم واتساب عادي — بدون حساب Meta Business وبدون طابور موافقات.

التثبيت

منشورة على npm باسم wasaas (الإصدار 0.1.0). No runtime dependencies، فلا تضيف شيئًا لشجرة الاعتماديات غير نفسها.

bash
npm install wasaas

المصادقة

أنشئ مفتاح API من لوحة التحكم تحت API Keys. تبدأ المفاتيح بـ wsa_، والعميل يرفض أي مفتاح لا يبدأ بهذا الشكل فور الإنشاء، بدلًا من الفشل عند أول طلب.

javascript
import { Wasaas } from "wasaas";

const client = new Wasaas({
  apiKey: process.env.WASAAS_API_KEY, // يجب أن يبدأ بـ wsa_
});

يوجد خيار baseUrl وقيمته الافتراضية https://wasaas.org؛ تحتاجه فقط عند الإشارة إلى بيئة مختلفة.

إرسال رسالة

تحتاج معرّف الجلسة لرقم واتساب متصل — يظهر في لوحة التحكم بعد مسح رمز QR، ويُعاد أيضًا من client.sessions.list(). أرقام المستلمين بصيغة دولية بدون علامة + في البداية.

javascript
const res = await client.messages.sendText({
  sessionId: "customer-5-1",
  to: "966501234567",
  message: "تم شحن طلبك.",
});

// { success: true, to: "966501234567", status: "sent" }

الصور والمستندات

الصور تُرسل برابط URL. المستندات تُرسل كـ base64، مما يعني أنك تستطيع توليد فاتورة أو تقرير في الذاكرة وإرساله مباشرة بدون استضافته على رابط عام.

javascript
await client.messages.sendImage({
  sessionId: "customer-5-1",
  to: "966501234567",
  imageUrl: "https://example.com/receipt.png",
  caption: "فاتورتك",           // اختياري
});

await client.messages.sendDocument({
  sessionId: "customer-5-1",
  to: "966501234567",
  base64: pdfBuffer.toString("base64"),
  filename: "invoice-1042.pdf",
  mime: "application/pdf",
});

النص والصورة والمستند هي أنواع الرسائل المدعومة. الرسائل الصوتية والموقع الجغرافي والأزرار التفاعلية غير متاحة.

التحقق من رقم قبل الإرسال

ليس كل رقم هاتف لديه واتساب. التحقق أولًا يبقي محاولات الإرسال الفاشلة خارج سجلاتك وخارج حصتك.

javascript
const check = await client.numbers.validate({
  sessionId: "customer-5-1",
  phone: "966501234567",
});

if (check.has_whatsapp) {
  // آمن للإرسال
}

التعامل مع الأخطاء

الاستجابات غير الناجحة ترمي WasaasAPIError، والتي تحمل رمز status ونصًا توضيحيًا detail عند توفره.

javascript
import { WasaasAPIError } from "wasaas";

try {
  await client.messages.sendText({ sessionId, to, message });
} catch (err) {
  if (err instanceof WasaasAPIError) {
    // 401 مفتاح غير صالح · 404 الجلسة غير موجودة · 429 تجاوز الحصة
    console.error(err.status, err.message, err.detail);
    return;
  }
  throw err;
}

رمز 429 يعني استهلاك الحصة الشهرية للرسائل؛ راجع أسعار واجهة API للواتساب لمعرفة حدود كل باقة.

الإرسال الجماعي ليس ضمن المكتبة بعد

تغطي المكتبة الإرسال الفردي والجلسات والتحقق من الأرقام. لإرسال رسالة لعدد كبير من المستلمين دفعة واحدة، استخدم نقطة نهاية REST مباشرة — فهي تتكفل بتهدئة الإرسال نيابة عنك. راجع واجهة الإرسال الجماعي (بالإنجليزية).

حدود حقيقية

هذا ربط غير رسمي ومبني على الجلسات عبر رمز QR، وليس منصة واتساب الرسمية لمنتجات الأعمال. لا يوجد حاليًا إرسال أحداث (webhooks) إلى سيرفرك الخاص عند وصول أو إرسال رسالة.

إلى أين تذهب بعد ذلك

ربط واتساب مع Node.js — مكتبة wasaas الرسمية | Wasaas