API الرسائل
API جدولة رسائل WhatsApp
جدوِل نصًا أو صورة أو مستندًا عبر WhatsApp ليُرسَل إلى رقم هاتف أو مجموعة في التاريخ والوقت اللذين تختارهما. استخدمه لتذكيرات المواعيد، وتهاني أعياد الميلاد، والمتابعات، والعروض المرتبطة بوقت محدد.
https://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"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/schedule_msg/",
json={
"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",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Scheduled with msg_id", result["msg_id"])
else:
print("Failed:", result.get("message", "no message in response"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/schedule_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Scheduled with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message ?? "no message in response");
}<?php
$payload = [
'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',
];
$ch = curl_init('https://wbiztool.com/api/v1/schedule_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Scheduled with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no message in response');
}استبدل 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_code91إلى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). كل اختصار يقابل منطقة، ويُطبَّق التوقيت الصيفي لتلك المنطقة تلقائيًا:
| الاختصار | يُعامَل على أنه |
|---|---|
IST | Asia/Kolkata |
UTC | UTC |
GMT | GMT |
EST | US/Eastern |
CST | US/Central |
MST | US/Mountain |
PST | US/Pacific |
CET، CEST | Europe/Paris |
EET، EEST | Europe/Athens |
JST | Asia/Tokyo |
AEST، AEDT | Australia/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"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/schedule_msg/",
json={
"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",
},
timeout=60,
)
print(response.json())// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/schedule_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/schedule_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'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',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);الاستجابة#
يُرجع الطلب الناجح HTTP 200:
{
"msg_id": 9817263,
"message": "Created",
"status": 1
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 إذا جُدولت الرسالة، و0 إذا فشل الطلب. |
message | string | Created عند النجاح، وإلا نص الخطأ. |
msg_id | integer | معرّف الرسالة المجدولة. احفظه للتحقق من الحالة أو لإلغائها لاحقًا. يظهر عند النجاح فقط. |
لا تكرر الاستجابة الوقت المجدول أو المنطقة الزمنية، لذا سجّل ما أرسلته.
الأخطاء#
تُرجع معظم الأخطاء 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الذي لا تقرؤه نقطة النهاية هذه. استدعِ نقطة النهاية مباشرةً كما هو موضح أعلاه. -
الرسائل المتكررة: للرسائل التي تتكرر، مثل تذكيرات الدفع الشهرية، راجع إنشاء تذكير.

