الإرسال إلى أرقام كثيرة
طلب واحد، حتى 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 مع صف عناوين، وحوّل كل صف إلى مستلم:
phone,name,code
+201001234567,Mona,EID20
+201112223334,Karim,EID15import { 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).
اطلع على التسويقية مقابل الخدمية لتعرف أي القواعد تنطبق على أي قوالب.