انتقل إلى المحتوى
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 بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

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

المصادقة

client_idintegerمطلوب

معرّف العميل في API ‏(API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).

api_keystringمطلوب

مفتاح API الخاص بك من الصفحة نفسها.

whatsapp_clientintegerمطلوب

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

الجدولة

datestringمطلوب

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

timestringمطلوب

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

timezonestringاختياري

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

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

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

رقم WhatsApp الخاص بالمستلم، أرقام فقط. تُزال المسافات و+ و- و. والأقواس تلقائيًا. أرسل الرقم إمّا مع رمز الدولة (919876543210) أو بدونه (9876543210) مع country_code.

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

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

country_codestringاختياري

رمز الاتصال الدولي للدولة بدون +، مثل 91 للهند أو 1 للولايات المتحدة. يُضاف قبل phone إلا إذا كان الرقم يبدأ به بالفعل. استثناء: مع 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 عند إرسال الرسالة أو فشلها. البيانات المرسلة هي نفسها كما في إرسال رسالة.

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

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

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

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

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

الاختصارات يجب أن تكون بأحرف كبيرة. كل اختصار يقابل منطقة، ويُطبَّق التوقيت الصيفي لتلك المنطقة تلقائيًا:

الاختصاريُعامَل على أنه
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 رقمًا)، ويمكن أن يبدأ بـ +.
Invalid Contact Number "…"بعد إضافة رمز الدولة، يجب أن يتكون الرقم من 6 إلى 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 نص فارغ.
Not enough creditsلم يتبقَّ في باقتك أي رسائل.
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 الذي لا تقرؤه نقطة النهاية هذه. استدعِ نقطة النهاية مباشرةً كما هو موضح أعلاه.

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