انتقل إلى المحتوى
مستندات المطورينتجريبي

الإرسال إلى أرقام كثيرة

طلب واحد، حتى 10,000 مستلم، لكل منهم متغيراته.

الإرسال إلى أرقام كثيرة هو الطلب نفسه بمستلمين أكثر: حتى 10,000 في الحملة الواحدة. ولكل مستلم متغيراته، فيحصل كل عميل على اسمه أو كوده أو رابطه.

{
  "name": "Eid offer",
  "template": { "id": "tpl_8Kq2mZ" },
  "from": "num_3Fh7Ws",
  "scheduledAt": "2026-12-01T09:00:00+02:00",
  "recipients": [
    { "phone": "+201001234567", "externalId": "cus_1", "variables": { "body": ["Mona"] } },
    { "phone": "+201112223334", "externalId": "cus_2", "variables": { "body": ["Karim"] } }
  ]
}

من CSV إلى JSON

معظم القوائم تبدأ كجدول بيانات. صدّره بصيغة CSV مع صف عناوين، وحوّل كل صف إلى مستلم:

customers.csv
phone,name,code
+201001234567,Mona,EID20
+201112223334,Karim,EID15
import { readFileSync } from 'node:fs';

// For real files with quotes or commas inside cells, use a CSV parser such as csv-parse.
const [header, ...rows] = readFileSync('customers.csv', 'utf8').trim().split('\n');
const cols = header.split(',');
const recipients = rows.map((line) => {
  const row = Object.fromEntries(line.split(',').map((v, i) => [cols[i], v.trim()]));
  return { phone: row.phone, name: row.name, variables: { body: [row.name, row.code] } };
});

أرقام الهواتف في جداول البيانات

كثيرًا ما تحذف جداول البيانات علامة + أو الصفر في أول الرقم. أرسل بصيغة E.164 (+201001234567)، ويعمل أيضًا الرقم المصري المحلي بصفره (01001234567) ويُقرأ على أنه +20. أي رقم آخر يحتاج إلى رمز دولته.

أكثر من 10,000 رقم

قسّم القائمة إلى أجزاء لا يزيد كل منها على 10,000، وأرسل حملة لكل جزء، ولكل حملة Idempotency-Key خاص (eid-offer-part-1، eid-offer-part-2…). يوزع موجود الإرسال على الوقت لكل رقم، لذا فإن بدء الأجزاء معًا لا يجعل التسليم أسرع.

منع التكرار

Idempotency-Key مطلوبة. قد تنتهي مهلة طلب كبير عندك بعد أن يكون موجود قد قبله، وإعادة المحاولة بالمفتاح نفسه تعيد تلك الحملة (idempotent-replay: true) بدلًا من إرسال القائمة مرة ثانية. راجع ترويسة Idempotency-Key.

الاستجابة

{
  "id": "cmp_9Xa4Lr",
  "status": "preparing",
  "total": 900,
  "pacing": { "mode": "steady", "overHours": 6 },
  "pacingAdjusted": true,
  "estimatedCredits": 897,
  "skipped": [
    { "index": 12, "phone": "0223456789", "reason": "invalid_number" },
    { "index": 40, "phone": "+201001234567", "reason": "duplicate" }
  ]
}
  • skipped يذكر الأرقام التي استُبعدت من الحملة بترتيبها في recipients: invalid_number (ليس رقم موبايل صالحًا) أو duplicate (الرقم نفسه، أو رقم آخر للعميل نفسه، جاء قبله). وإذا لم يكن أي رقم صالحًا، يفشل الطلب بـ 422 no_valid_recipients.
  • total يعدّ صفوف الحملة، ومنها العملاء الذين ألغوا اشتراكهم: يدخلون الحملة بحالة skipped (opted_out) من البداية ولا يُرسل إليهم شيء.
  • pacingAdjusted: true تعني أن موجود اختار سرعة الإرسال أو رفعها لتناسب حد الإرسال دفعة واحدة. راجع حدود الطلبات وتوزيع الإرسال.

وضع المراجعة

في بعض مساحات العمل تنتظر الحملات موافقة فريق موجود، فتبدأ بالحالة in_review. وبعد الموافقة تنتقل وحدها إلى scheduled أو preparing، ويصلك campaign.started عندما يبدأ الإرسال. وإذا رفضها الفريق يصلك campaign.rejected مع reviewNote، ولا يُرسل شيء.

من يتم تخطيه لاحقًا

بعد بدء الحملة قد يصبح المستلم skipped أيضًا، مع skipReason:

skipReasonالسبب
opted_outألغى العميل اشتراكه في رسائلك.
frequency_capوصلته رسالة حملة مؤخرًا (للتسويقية فقط).
contact_deletedحُذف العميل من جهات الاتصال قبل الإرسال.
offer_endedانتهى العرض محدود الوقت لحملة من لوحة التحكم قبل الإرسال.

أما حد واتساب نفسه لعدد الرسائل التسويقية لكل شخص فليس تخطيًا: ترفض ميتا الرسالة، فتصبح failed مع كود ميتا في error.code (مثل 131049).

اطلع على التسويقية مقابل الخدمية لتعرف أي القواعد تنطبق على أي قوالب.

في هذه الصفحة