واتساب API في Node.js: إرسال رسالة واتساب من Node.js وExpress بمثال كامل
إرسال رسالة واتساب من Node.js عبر API الرسمي: دالة واحدة بـfetch المدمج، وإرسال قالب معتمد ومعرفة حالته، ومسار Express يرسل إشعار الشحن، والأخطاء الشائعة.
في هذه الصفحة 7
الإجابة المختصرة
لإرسال رسالة واتساب من Node.js يكفي fetch المدمج في الإصدار ١٨ وما بعده: نداء إلى POST https://app.arabybot.com/api/v1/messages/template بمفتاحك في ترويسة Authorization وجسم JSON فيه رقم المستلم واسم القالب المعتمد ومتغيراته. النداء من الخادم وحده لا من المتصفح. وهذا الطريق الرسمي؛ أما مكتبات جلسة واتساب ويب فغير رسمية وتعرّض الرقم للحظر.
يُسأل عنها أيضًا: «whatsapp api node js» · «ارسال رسالة واتساب node js» · «ارسال واتساب جافاسكربت» · «whatsapp api javascript»
الطريق الرسمي لا جلسة واتساب ويب
أشهر ما يجده من يبحث عن واتساب في Node.js مكتبات تشغّل جلسة واتساب ويب وترسل منها. سهلة في البداية، ثم يأتي ما لا يُحسب حسابه: واتساب يقيّد الحسابات التي يبدو نشاطها آليًّا ثم يحظرها، والجلسة تنقطع فتحتاج إلى مسح الرمز من جديد. الكود هنا يرسل عبر واجهة واتساب للأعمال الرسمية من رقمك المتصل بعربي بوت، بلا جلسة ولا رمز.
مدة حظر الواتساب وأنواعه · تطبيق واتساب للأعمال أم واتساب API؟
ما تحتاجه
- رقم واتساب متصل بعربي بوت وعليه قالب معتمد واحد على الأقل.
- باقة تشمل «أدوات المطورين»: «WhatsApp Pro» أو «WhatsApp Premium» أو «Complete Plan» أو «Ultimate Plan».
- مفتاح من صفحة «أدوات المطورين»، يبدأ بـ
abk_ويظهر مرة واحدة. ضعه في متغير البيئةARABYBOT_API_KEYعلى الخادم.
دالة واحدة بـfetch المدمج
// arabybot.mjs — Node.js 18 or newer: fetch is built in, nothing to install.
const BASE = 'https://app.arabybot.com/api/v1';
const KEY = process.env.ARABYBOT_API_KEY;
export async function arabybot(method, path, body) {
try {
const res = await fetch(`${BASE}/${path}`, {
method,
headers: {
Authorization: `Bearer ${KEY}`,
...(body ? { 'Content-Type': 'application/json' } : {}),
},
body: body ? JSON.stringify(body) : undefined,
signal: AbortSignal.timeout(20000),
});
return await res.json();
} catch {
return { success: false, error_code: 'NETWORK' };
}
}
const me = await arabybot('GET', 'me'); // does the key work, and from which numbers?
const templates = await arabybot('GET', 'templates'); // each template has a ready body in "example" الملف بامتداد .mjs ليعمل await في أعلى الملف. وAbortSignal.timeout يقطع الطلب بعد عشرين ثانية بدل أن يبقى معلّقًا.
إرسال قالب ومعرفة حالته
import { arabybot } from './arabybot.mjs';
const sent = await arabybot('POST', 'messages/template', {
to: '201012345678', // with the country code
template: 'order_shipped',
language: 'ar',
variables: ['Ahmed', '1042'], // the template's {{1}}, {{2}} in order
reference: 'order-1042-shipped', // the same reference is never sent twice
});
if (sent.success) {
await saveMessageId(orderId, sent.id); // "accepted", or "queued": it goes out by itself
} else if (['TRY_AGAIN', 'NETWORK'].includes(sent.error_code)) {
await retryLater(orderId); // same request, same reference
} else if (sent.error_code === 'UNCERTAIN') {
await checkLater(sent.id); // ask GET messages/{id} before sending again
} else {
console.error(sent.error_code, sent.message_en);
}
const status = await arabybot('GET', 'messages/512'); // queued · accepted · sent · delivered · read · failed الرد الناجح حالته accepted أو queued. والثانية ليست خطأ: معناها أن رسائل رقمك تخرج بالسرعة التي يقبلها واتساب وأن هذه تنتظر دورها لحظات. وreference يحميك حين يعيد خادمك الطلب بعد انقطاع: يعود الرد بالرسالة الأولى ومعها duplicate: true.
كل الحقول ورموز الرفض والحدود في مرجع واجهة الإرسال
مثال عملي: إشعار الشحن من خادم Express
import express from 'express';
import { arabybot } from './arabybot.mjs';
const app = express();
app.use(express.json());
// your shop calls this when an order ships
app.post('/orders/:id/shipped', async (req, res) => {
const { phone, name } = req.body;
const sent = await arabybot('POST', 'messages/template', {
to: phone,
template: 'order_shipped',
language: 'ar',
variables: [name, req.params.id],
reference: `order-${req.params.id}-shipped`,
});
res.status(sent.success ? 200 : 502).json({ ok: Boolean(sent.success), code: sent.error_code ?? null });
});
app.listen(3000); نظام متجرك ينادي هذا المسار حين يُشحن الطلب، والمسار يرسل القالب من رقمك. وإن كان متجرك على شوبيفاي أو ووكومرس أو إيزي أوردرز أو لايت فانلز فلا تحتاج إلى هذا الكود أصلًا: تأكيد الطلبات ورسائل الحالة تعمل من الربط الجاهز.
أخطاء شائعة في Node.js
| الخطأ | ما يحدث | الحل |
|---|---|---|
| المفتاح في كود الواجهة الأمامية | يراه كل زائر ويرسل من رقمك | الخادم وحده، وprocess.env |
نسيان await | تقرأ وعدًا لا ردًّا، فيبدو كل طلب ناجحًا | await قبل كل نداء |
جسم بلا JSON.stringify | BAD_JSON | كما في الدالة أعلاه |
Promise.all على آلاف الرسائل | تتجاوز ٦٠٠ طلب في الدقيقة ويعود ٤٢٩ | أرسل على دفعات صغيرة متتابعة |
| إعادة كل رفض | طلبات بلا فائدة | أعد TRY_AGAIN وحده |
الشرح نفسه بلغة PHP · وبلغة بايثون · ومن n8n بلا كود
الأسئلة الشائعة
هل أستخدم مكتبات واتساب ويب في Node.js؟
لا ننصح بها لرقم نشاط. هذه المكتبات تشغّل جلسة واتساب ويب وترسل منها آليًّا، وهي غير رسمية: واتساب يعدّ الإرسال الآلي من التطبيق مخالفة تنتهي إلى تقييد الحساب أو حظره. الكود في هذه الصفحة يرسل عبر واجهة واتساب للأعمال الرسمية.
هل أستطيع استدعاء الواجهة من المتصفح أو من تطبيق React؟
لا. المفتاح يرسل من رقمك، وأي كود يعمل في المتصفح يراه الزائر. استدعِ الواجهة من خادمك، ودَع الواجهة الأمامية تطلب من خادمك أنت.
أي إصدار من Node.js أحتاجه؟
الإصدار ١٨ أو أحدث، ففيه fetch وAbortSignal.timeout مدمجان. وعلى إصدار أقدم استخدم مكتبة طلبات تعرفها، فالواجهة نداءات HTTP عادية.
كيف أعرف أن الرسالة وصلت من غير أن أسأل كل مرة؟
اسأل عن الحالة حين تحتاجها فقط، كعند فتح صفحة الطلب في لوحتك. والرسالة تظهر كذلك في الدردشة المباشرة داخل عربي بوت بعلامات التسليم والقراءة.
اقرأ بعدها
جرّب الوكيل قبل أن تدفع شيئًا
الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.