التكاملات

واتساب API في Node.js: إرسال رسالة واتساب من Node.js وExpress بمثال كامل

إرسال رسالة واتساب من Node.js عبر API الرسمي: دالة واحدة بـfetch المدمج، وإرسال قالب معتمد ومعرفة حالته، ومسار Express يرسل إشعار الشحن، والأخطاء الشائعة.

8 دقائق قراءة آخر تحديث 15 نوفمبر 2026 فريق عربي بوت
فريق عربي بوتشريك Meta الرسمي · نكتب من بيانات منصتنا
في هذه الصفحة 7
  1. الطريق الرسمي لا جلسة واتساب ويب
  2. ما تحتاجه
  3. دالة واحدة بـfetch المدمج
  4. إرسال قالب ومعرفة حالته
  5. مثال عملي: إشعار الشحن من خادم Express
  6. أخطاء شائعة في Node.js
  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.stringifyBAD_JSONكما في الدالة أعلاه
Promise.all على آلاف الرسائلتتجاوز ٦٠٠ طلب في الدقيقة ويعود ٤٢٩أرسل على دفعات صغيرة متتابعة
إعادة كل رفضطلبات بلا فائدةأعد TRY_AGAIN وحده

الشرح نفسه بلغة PHP · وبلغة بايثون · ومن n8n بلا كود

الأسئلة الشائعة

1

هل أستخدم مكتبات واتساب ويب في Node.js؟

لا ننصح بها لرقم نشاط. هذه المكتبات تشغّل جلسة واتساب ويب وترسل منها آليًّا، وهي غير رسمية: واتساب يعدّ الإرسال الآلي من التطبيق مخالفة تنتهي إلى تقييد الحساب أو حظره. الكود في هذه الصفحة يرسل عبر واجهة واتساب للأعمال الرسمية.

2

هل أستطيع استدعاء الواجهة من المتصفح أو من تطبيق React؟

لا. المفتاح يرسل من رقمك، وأي كود يعمل في المتصفح يراه الزائر. استدعِ الواجهة من خادمك، ودَع الواجهة الأمامية تطلب من خادمك أنت.

3

أي إصدار من Node.js أحتاجه؟

الإصدار ١٨ أو أحدث، ففيه fetch وAbortSignal.timeout مدمجان. وعلى إصدار أقدم استخدم مكتبة طلبات تعرفها، فالواجهة نداءات HTTP عادية.

4

كيف أعرف أن الرسالة وصلت من غير أن أسأل كل مرة؟

اسأل عن الحالة حين تحتاجها فقط، كعند فتح صفحة الطلب في لوحتك. والرسالة تظهر كذلك في الدردشة المباشرة داخل عربي بوت بعلامات التسليم والقراءة.

فريق عربي بوتشريك Meta الرسمي للأعمال في الشرق الأوسط 239 دليلًا أرقام من منصتنا كل الأدلة

كيف نكتب هذه الأدلة الأرقام من منصتنا وفواتير ميتا الفعلية ومؤرّخة بعيّنتها، والوصف لما يعمل اليوم لا لما نعد به، ونذكر ما لا نفعله ومتى يكون غيرنا الخيار الأفضل. راجعه فريق عربي بوت في 15 نوفمبر 2026.

شارك الدليل
وتديره كله من موبايلككل ما في هذه الصفحة تديره من تطبيق عربي بوت على جوالك — الردود والطلبات والحملات وتقارير الذكاء الاصطناعي. لا لوحة تحكم على الويب فحسب.

جرّب الوكيل قبل أن تدفع شيئًا

الوكيل الذي يرد على عملائك هو نفسه الذي يرد عليك الآن: اسأله من زر الدردشة هنا أو على واتساب. وحسابك مجاني بلا بطاقة ائتمان، والتجربة المجانية على رقمك أو صفحتك تُفعَّل بعد التواصل مع الإدارة على واتساب خدمة العملاء.