انتقل إلى المحتوى
WbizTool

API الرسائل

API جدولة رسائل WhatsApp

جدوِل نصًا أو صورة أو مستندًا عبر WhatsApp ليُرسَل إلى رقم هاتف أو مجموعة في التاريخ والوقت اللذين تختارهما. استخدمه لتذكيرات المواعيد، وتهاني أعياد الميلاد، والمتابعات، والعروض المرتبطة بوقت محدد.

POSThttps://wbiztool.com/api/v1/schedule_msg/

النص (Body): JSON أو حقول نموذج

تنتظر الرسالة في قائمة الانتظار حتى الوقت المجدول، ثم تُرسَل من رقم WhatsApp الخاص بك. تمنحك الاستجابة msg_id يمكنك استخدامه للتحقق من حالتها أو لإلغائها.

مثال سريع#

curl -X POST https://wbiztool.com/api/v1/schedule_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, a reminder that your appointment is today at 11:30 AM.",
    "date": "24/12/2026",
    "time": "09:00",
    "timezone": "Asia/Kolkata"
  }'

استبدل 12345 وYOUR_API_KEY و678 بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

معاملات الطلب#

المصادقة

Authorizationheaderموصى به

‏Bearer YOUR_API_KEY: مفتاح API الخاص بك من Settings → API keys (الإعدادات ← مفاتيح API). مع الترويسة، يمكن حذف client_id وapi_key من الجسم؛ وإذا أُرسل المفتاح في الترويسة والجسم معًا، يُستخدم مفتاح الترويسة إذا كان صالحًا. راجع إرسال المفتاح في ترويسة.

client_idintegerبدون ترويسة Authorization

معرّف العميل في API ‏(API Client ID) من Settings → API keys. اختياري مع الترويسة؛ وإذا أرسلته، فيجب أن يكون لمساحة عمل المفتاح.

api_keystringبدون ترويسة Authorization

مفتاح API الخاص بك من الصفحة نفسها، عندما لا ترسله في الترويسة.

whatsapp_clientintegerمطلوب

معرّف رقم WhatsApp أو حساب Telegram الذي ستُرسَل منه الرسالة، من إعدادات WhatsApp. على عكس إرسال رسالة، لا تختار نقطة النهاية هذه رقمًا نيابةً عنك أبدًا.

الجدولة

datestringمطلوب

يوم إرسال الرسالة، بالصيغة dd/mm/yyyy، مثل 24/12/2026.

timestringمطلوب

وقت إرسال الرسالة، بصيغة 24 ساعة HH:MM، مثل 09:00 أو 18:45. لا تضع الثواني.

timezonestringاختياري

المنطقة الزمنية التي يُقرأ بها date وtime. القيمة الافتراضية IST (الهند) إذا حذفته. راجع المناطق الزمنية.

المستلم والرسالة

phonestringمطلوب ما لم ترسل group_name

رقم WhatsApp الخاص بالمستلم. تُزال المسافات و+ و- و. والأقواس و00 البادئة تلقائيًا، لذا يعمل ‎+91 98765-43210. وتُقرأ قيم جداول البيانات مثل 919876543210.0 و9.19876543210E+11 كخاناتها، أما القيمة المقرَّبة مثل 9.19877E+11 فتُرفض، لأن بعض الخانات مفقودة. أرسل الرقم إمّا مع رمز الدولة (919876543210) أو بدونه (9876543210) مع country_code. ويعمل أيضًا الرقم المحلي المكتوب مع الصفر البادئ: يذهب 09876543210 مع country_code 91 إلى 919876543210، ويذهب 0612345678 مع 39 (إيطاليا، حيث الصفر جزء من الرقم) إلى 390612345678. الرقم المكتوب مع + أو 00 يحمل رمز دولته: لا يُضاف إليه country_code، ويُحذف ‎(0) بين القوسين بعد الرمز، لذا يذهب ‎+44 (0)20 7946 0018 إلى 442079460018. من حساب Telegram، يمكن أن تكون قيمة phone أيضًا ‎@username أو رابط t.me/username أو tg:<id>.

group_namestringمطلوب ما لم ترسل phone

اسم مجموعة WhatsApp يكون رقمك عضوًا فيها. يُعثر عليها بالطريقة نفسها المتبعة في الإرسال إلى مجموعة. أرسل phone أو group_name، ولا ترسلهما معًا أبدًا.

country_codestringاختياري

رمز الاتصال الدولي للدولة بدون +، مثل 91 للهند أو 1 للولايات المتحدة. يُضاف قبل phone إلا إذا كان الرقم يبدأ به بالفعل أو كان مكتوبًا مع + أو 00. استثناء: مع 91، يحصل الرقم المكوّن من 10 أرقام على البادئة دائمًا. ومع الرموز الأخرى، أرسل الأرقام المحلية التي تبدأ بالأرقام نفسها متضمنةً رمز الدولة. يُتجاهل مع المجموعات.

msg_typeintegerاختياري

‏0 نص (افتراضي)، و1 صورة، و2 ملف أو مستند.

msgstringمطلوب عندما تكون قيمة msg_type هي 0

نص الرسالة. للصور والملفات يكون هو التعليق (caption) ويمكن أن يكون فارغًا. يعمل تنسيق WhatsApp: *bold* و_italic_ و~strikethrough~. ويُقبل message كاسم بديل.

الصور والملفات

img_urlstringمطلوب عندما تكون قيمة msg_type هي 1

عنوان URL عام للصورة يبدأ بـ http أو https.

file_urlstringمطلوب عندما تكون قيمة msg_type هي 2

عنوان URL عام يبدأ بـ http أو https ويمكن تنزيل الملف منه مباشرةً.

file_namestringاختياري

اسم الملف الذي يراه المستلم، مثل invoice-4821.pdf. يُرسَل بأحرف صغيرة، وتُستبدل أحرف مثل & : ? * $ ; بـ _، ويُقتطع عند 150 حرفًا. إذا حذفته، يُؤخذ الاسم من عنوان URL.

خيارات الإرسال

webhookstringاختياري

عنوان URL يستقبل طلب POST عند إرسال الرسالة أو فشلها أو إلغائها أو انتهاء صلاحيتها. البيانات المرسلة هي نفسها كما في إرسال رسالة.

idempotency_keystringاختياري

اختياري، حتى 255 حرفًا. لمدة 24 ساعة، إذا أعدت المحاولة بالقيمة نفسها تحصل على الاستجابة الأولى بدلًا من رسالة ثانية. ويمكنك إرساله بدلًا من ذلك في ترويسة Idempotency-Key. راجع إعادة المحاولة بأمان.

متى تُرسل الرسالة#

  • يحوّل WbizTool قيم date وtime وtimezone إلى لحظة واحدة، ويرسل الرسالة بمجرد مرور تلك اللحظة، ما دام رقم WhatsApp الخاص بك متصلًا.
  • الوقت الماضي مقبول. تُرسَل الرسالة فورًا، مثل الإرسال العادي. تحقّق جيدًا من صيغة التاريخ (dd/mm/yyyy، اليوم أولًا) حتى لا ترسل رسالة قبل موعدها بأشهر.
  • إذا كان رقمك غير متصل في الوقت المجدول، فستنتظر الرسالة وتُرسَل بمجرد عودة اتصال الرقم، حتى لو كان ذلك بعد الموعد المخطط بوقت طويل. لا توجد مدة صلاحية في نقطة النهاية هذه، لذا ألغِ الرسالة إذا لم تعد مناسبة. تُحذف الرسالة التي لا تزال تنتظر على رقم غير متصل أو محذوف بعد 90 يومًا من وقتها المجدول.
  • حتى تُرسَل، تكون حالة الرسالة 0 (Created) ويمكن إلغاؤها. وتُحتسب ضمن الحد اليومي للرقم في يوم جدولتها (وضمن رسائل الباقة المجانية).

المناطق الزمنية#

يقبل timezone إمّا اسم منطقة زمنية أو أحد الاختصارات أدناه.

أسماء المناطق الزمنية مثل Asia/Kolkata أو America/New_York أو Europe/London أو Australia/Sydney. يعمل أي اسم من قاعدة بيانات المناطق الزمنية IANA. وهذا هو الخيار الأكثر موثوقية. راجع مرجع المناطق الزمنية للاطلاع على القائمة.

الاختصارات تعمل بأحرف كبيرة أو صغيرة (IST أو ist). كل اختصار يقابل منطقة، ويُطبَّق التوقيت الصيفي لتلك المنطقة تلقائيًا:

الاختصاريُعامَل على أنه
ISTAsia/Kolkata
UTCUTC
GMTGMT
ESTUS/Eastern
CSTUS/Central
MSTUS/Mountain
PSTUS/Pacific
CET، CESTEurope/Paris
EET، EESTEurope/Athens
JSTAsia/Tokyo
AEST، AEDTAustralia/Sydney

مثلًا، EST في يوليو تعني التوقيت الصيفي لنيويورك (UTC−4)، وليس UTC−5 الثابت.

الجدولة لمجموعة#

curl -X POST https://wbiztool.com/api/v1/schedule_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "group_name": "Sales Team Mumbai",
    "msg": "Team meeting starts in 15 minutes.",
    "date": "24/12/2026",
    "time": "14:45",
    "timezone": "Asia/Kolkata"
  }'

الاستجابة#

يُرجع الطلب الناجح HTTP 200:

{
  "msg_id": 9817263,
  "message": "Created",
  "status": 1
}
الحقلالنوعالوصف
statusinteger‏1 إذا جُدولت الرسالة، و0 إذا فشل الطلب.
messagestring‏Created عند النجاح، وإلا نص الخطأ.
msg_idintegerمعرّف الرسالة المجدولة. احفظه للتحقق من الحالة أو لإلغائها لاحقًا. يظهر عند النجاح فقط.

لا تكرر الاستجابة الوقت المجدول أو المنطقة الزمنية، لذا سجّل ما أرسلته.

الأخطاء#

تُرجع معظم الأخطاء HTTP 200 مع status بقيمة 0، لذا تحقّق دائمًا من status في الجسم:

{ "message": "Scheduled date & time is not in valid format", "status": 0 }
الرسالةطريقة الإصلاح
Auth Errorأرسل client_id وapi_key كليهما.
Invalid Client Idأرسل client_id كرقم. يُرجَع مع HTTP 403.
Auth Error: invalid api keyتأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400.
Either phone or group_name parameter is requiredأضف phone أو group_name.
Please provide either phone OR group_name, not bothاحذف أحدهما.
Invalid phone numberيجب أن يكون phone رقمًا من 6 إلى 17 خانة. لا يُسمح بالأحرف والرموز الأخرى، ولا بقيمة جدول بيانات مقرَّبة مثل 9.19877E+11.
Invalid Contact Number "…"بعد إضافة رمز الدولة، يجب أن يتكون الرقم من 7 إلى 15 رقمًا.
Msg cant be nullالرسائل النصية (msg_type 0) تحتاج إلى msg.
Image Url Can't be nullمع msg_type 1، أرسل img_url.
File Url Can't be nullمع msg_type 2، أرسل file_url.
Scheduled date & time is not in valid format‏date أو time مفقود، أو أن timezone نص فارغ.
Scheduled date & time is not in valid format: date DD/MM/YYYY and time HH:MM (24-hour)‏date أو time بصيغة أخرى (مثل 2026-12-24 أو 09:00:00) أو ليس تاريخًا حقيقيًا (31/02/2026).
Unknown timezone "…": …‏timezone ليس اسم منطقة زمنية ولا أحد الاختصارات أعلاه. لا تُقبل الفروق مثل GMT+5:30.
Invalid msg_type: use 0 (text), 1 (image) or 2 (file)أرسل msg_type بالقيمة 0 أو 1 أو 2.
Invalid whatsapp client …‏whatsapp_client مفقود أو ليس أحد أرقامك. استخدم المعرّف المعروض للرقم المتصل في لوحة التحكم.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientيحتاج ‎@username أو رابط t.me أو tg:<id> في phone إلى حساب Telegram كـ whatsapp_client.
Server error: the message was not scheduled. Please try again.حدث عطل من جانبنا. تُرجَع مع HTTP 500؛ لم تُجدوَل أي رسالة، لذا حاول مرة أخرى.
Not enough creditsمساحة العمل على الباقة المجانية ولم تتبقَّ لها رسائل: ترسل الباقات المدفوعة رسائل غير محدودة. راجع عند نفاد رسائلك.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. ‏(HTTP 429، "code": "daily_limit_reached")استقبل هذا الرقم 1,000 رسالة خلال آخر 24 ساعة (الاستخدام العادل). لا تزال الاستجابة تتضمن msg_id للرسالة المرفوضة، التي تظهر فاشلة. أرسل الباقي لاحقًا أو من رقم آخر.
Demo Account can not access apisاستخدم حسابًا عاديًا.
Invalid JSON format: …جسم JSON غير صالح، أو أنك أرسلت حقول نموذج بدون client_id.

نصائح#

  • كوّن التاريخ بعناية: في Python استخدم strftime("%d/%m/%Y") وstrftime("%H:%M"). وفي JavaScript، نسّق التاريخ والوقت بالمنطقة الزمنية نفسها التي ترسلها في timezone، لا بالتوقيت المحلي لخادمك:

    const tz = "Asia/Kolkata"; // d is the Date to send at
    const date = new Intl.DateTimeFormat("en-GB", { timeZone: tz, day: "2-digit", month: "2-digit", year: "numeric" }).format(d); // "24/12/2026"
    const time = new Intl.DateTimeFormat("en-GB", { timeZone: tz, hour: "2-digit", minute: "2-digit", hourCycle: "h23" }).format(d); // "09:00"
  • تأكد من الوقت: جدوِل رسالة اختبار بعد خمس دقائق وتحقّق من وصولها في الوقت المتوقع.

  • تغيير الخطط: لإعادة الجدولة، ألغِ الرسالة وجدوِل رسالة جديدة.

  • لا تستخدم المكتبات الرسمية للجدولة حاليًا: ترسل الدالة schedule_message في Python التاريخ بالصيغة YYYY-MM-DD (فتُرفض لأن الصيغة غير صالحة)، وترسل الدالة scheduleMessage في Node المعامل schedule_time الذي لا تقرؤه نقطة النهاية هذه. استدعِ نقطة النهاية مباشرةً كما هو موضح أعلاه.

  • الرسائل المتكررة: للرسائل التي تتكرر، مثل تذكيرات الدفع الشهرية، راجع إنشاء تذكير.