Node.js
ربط واتساب مع Node.js
مكتبة wasaas تُغلّف واجهة Wasaas البرمجية حتى ترسل رسائل واتساب من أي خدمة Node.js بدون كتابة استدعاءات HTTP يدويًا. تأتي بأنواع TypeScript، بدون أي اعتماديات تشغيل، وتعمل على رقم واتساب عادي — بدون حساب Meta Business وبدون طابور موافقات.
التثبيت
منشورة على npm باسم wasaas (الإصدار 0.1.0). No runtime dependencies، فلا تضيف شيئًا لشجرة الاعتماديات غير نفسها.
npm install wasaasالمصادقة
أنشئ مفتاح API من لوحة التحكم تحت API Keys. تبدأ المفاتيح بـ wsa_، والعميل يرفض أي مفتاح لا يبدأ بهذا الشكل فور الإنشاء، بدلًا من الفشل عند أول طلب.
import { Wasaas } from "wasaas";
const client = new Wasaas({
apiKey: process.env.WASAAS_API_KEY, // يجب أن يبدأ بـ wsa_
});يوجد خيار baseUrl وقيمته الافتراضية https://wasaas.org؛ تحتاجه فقط عند الإشارة إلى بيئة مختلفة.
إرسال رسالة
تحتاج معرّف الجلسة لرقم واتساب متصل — يظهر في لوحة التحكم بعد مسح رمز QR، ويُعاد أيضًا من client.sessions.list(). أرقام المستلمين بصيغة دولية بدون علامة + في البداية.
const res = await client.messages.sendText({
sessionId: "customer-5-1",
to: "966501234567",
message: "تم شحن طلبك.",
});
// { success: true, to: "966501234567", status: "sent" }الصور والمستندات
الصور تُرسل برابط URL. المستندات تُرسل كـ base64، مما يعني أنك تستطيع توليد فاتورة أو تقرير في الذاكرة وإرساله مباشرة بدون استضافته على رابط عام.
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",
});النص والصورة والمستند هي أنواع الرسائل المدعومة. الرسائل الصوتية والموقع الجغرافي والأزرار التفاعلية غير متاحة.
التحقق من رقم قبل الإرسال
ليس كل رقم هاتف لديه واتساب. التحقق أولًا يبقي محاولات الإرسال الفاشلة خارج سجلاتك وخارج حصتك.
const check = await client.numbers.validate({
sessionId: "customer-5-1",
phone: "966501234567",
});
if (check.has_whatsapp) {
// آمن للإرسال
}التعامل مع الأخطاء
الاستجابات غير الناجحة ترمي WasaasAPIError، والتي تحمل رمز status ونصًا توضيحيًا detail عند توفره.
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) إلى سيرفرك الخاص عند وصول أو إرسال رسالة.
إلى أين تذهب بعد ذلك
- واتساب API للمطورين — الصورة الكاملة: المكتبات وخطوات الربط
- توثيق REST API (بالإنجليزية) — كل نقطة نهاية وحقل تغلفه هذه المكتبة
- ربط واتساب مع Laravel — نفس الواجهة البرمجية من تطبيق PHP أو Laravel
- أسعار واجهة API للواتساب — حدود الرسائل والجلسات لكل باقة