API الرسائل
API الإرسال إلى عدة أرقام
أرسل رسالة WhatsApp نفسها إلى عدة أرقام هواتف ومجموعات في طلب واحد. استخدمه لعمليات البث الصغيرة مثل النشرات الإخبارية والعروض والإعلانات.
https://wbiztool.com/api/v1/send_msg/multi/النص (Body): JSON أو حقول نموذج
ينشئ WbizTool رسالة لكل مستلم ويُرجع msg_id لكل منها، حتى تتمكن من التحقق من حالتها كلٌّ على حدة.
مثال سريع#
curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
-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,9812345670,Sales Team Mumbai",
"msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/multi/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 0,
"country_code": "91",
"phone": ",".join(["9876543210", "9812345670", "Sales Team Mumbai"]),
"msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
for item in result["messages"]:
print(item["contact"], "->", item["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/send_msg/multi/", {
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", "9812345670", "Sales Team Mumbai"].join(","),
msg: "Our Diwali sale starts tomorrow. Get 20% off on all orders!",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
for (const item of result.messages) {
console.log(item.contact, "->", item.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' => implode(',', ['9876543210', '9812345670', 'Sales Team Mumbai']),
'msg' => 'Our Diwali sale starts tomorrow. Get 20% off on all orders!',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/multi/');
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) {
foreach ($result['messages'] as $item) {
echo $item['contact'] . ' -> ' . $item['msg_id'] . PHP_EOL;
}
} 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. على عكس إرسال رسالة، لا تختار نقطة النهاية هذه رقمًا نيابةً عنك أبدًا.
المستلمون والرسالة
phonestringمطلوبأرقام الهواتف وأسماء المجموعات في نص واحد مفصول بفواصل، مثل
9876543210,9812345670,Sales Team Mumbai. لا ترسل مصفوفة JSON. راجع طريقة قراءة المستلمين.country_codestringاختياريرمز الاتصال الدولي للدولة بدون
+، مثل91. يُضاف قبل كل رقم هاتف إلا إذا كان الرقم يبدأ به بالفعل أو كان مكتوبًا مع+أو00. في JSON، يعمل النص ("91") والرقم (91) كلاهما.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اختيارياسم الملف الذي يراه المستلمون، مثل
price-list.pdf. يُرسَل بأحرف صغيرة، وتُستبدل أحرف مثل& : ? * $ ;بـ_، ويُقتطع عند 150 حرفًا. إذا حذفته، يُؤخذ الاسم من عنوان URL.
خيارات الإرسال
webhookstringاختياريعنوان URL يستقبل طلب
POSTلكل رسالة عند إرسالها أو فشلها أو إلغائها أو انتهاء صلاحيتها. البيانات المرسلة هي نفسها كما في إرسال رسالة.idempotency_keystringاختيارياختياري، حتى 255 حرفًا. لمدة 24 ساعة، إذا أعدت المحاولة بالقيمة نفسها تحصل على الاستجابة الأولى بدلًا من رسالة ثانية. ويمكنك إرساله بدلًا من ذلك في ترويسة
Idempotency-Key. راجع إعادة المحاولة بأمان.
curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 1,
"country_code": "91",
"phone": "9876543210,9812345670",
"img_url": "https://example.com/offers/diwali-sale.jpg",
"msg": "Our Diwali sale starts tomorrow."
}'طريقة قراءة المستلمين#
يقسّم WbizTool قيمة phone عند الفواصل، ويحذف المسافات حول كل عنصر، ثم يحدّد نوع كل عنصر:
- أرقام الهواتف يمكن كتابتها كما هي لديك: تعمل كلها
+91 98765 43210و98765-43210و(987) 654-3210و0091 98765 43210و+44 (0)20 7946 0018، وكذلك قيم جداول البيانات مثل919876543210.0و9.19876543210E+11. country_codeيُضاف إلا إذا كان الرقم يبدأ به بالفعل أو كان مكتوبًا مع+أو00: يبقى +44 20 7946 0018معcountry_codeبقيمة91بالشكل442079460018. لذا يمكن أن تجمع القائمة الواحدة أرقامًا من عدة دول: اكتب أرقام الدول الأخرى مع+.- الرقم المحلي المكتوب مع الصفر البادئ يعمل أيضًا: يذهب
09876543210معcountry_codeبقيمة91إلى919876543210، ويذهب0612345678مع39(إيطاليا، حيث الصفر جزء من الرقم) إلى390612345678. - بعد إضافة رمز الدولة، يجب أن يتكون الرقم من 7 إلى 15 رقمًا.
- النص الذي يحتوي على أحرف أو رموز أخرى، مثل
Sales Team MumbaiأوFamily 2024، يُعامَل كاسم مجموعة WhatsApp، ويُعثر عليه بالطريقة نفسها المتبعة في الإرسال إلى مجموعة. - اسم المجموعة الذي لا يحتوي على أحرف، مثل
2024-2025، يُقرأ كرقم هاتف، إلا إذا كان فيه أقل من 10 خانات وسبق لمساحة عملك إرسال رسالة إلى مجموعة بهذا الاسم تمامًا (تظهر ضمن مجموعات في جهات الاتصال). أما الاسم القصير الذي فيه أقل من 7 خانات مع شرطة أو نقطة أو أقواس، مثل 2024-25أو (2024)، فهو دائمًا اسم مجموعة. ولا يمكن الإرسال من نقطة النهاية هذه إلى مجموعات تحتوي أسماؤها على فواصل. استخدم الإرسال إلى مجموعة لهذه الحالات. - من حساب Telegram، يكون
@usernameأو رابطt.me/usernameأوtg:<id>شخصًا لا اسم مجموعة، ويذهب رقم الهاتف إلى ذلك الشخص على Telegram. أما من رقم WhatsApp، فتُتخطّى أسماء المستخدمين وروابطt.meوtg:<id>.
أمور أخرى يجب معرفتها:
- الأرقام القصيرة جدًا أو الطويلة جدًا بعد إضافة رمز الدولة، وقيم جداول البيانات المقرَّبة، والعناصر المكوّنة من أصفار فقط (
0،00) تُتخطّى بصمت. لا تظهر في الاستجابة ولا تحصل علىmsg_id. - لا تُحذف الأرقام المكررة. الرقم المذكور مرتين يتلقى رسالتين.
- إذا صادف أن رقمًا محليًا يبدأ بالأرقام نفسها الموجودة في
country_code(مثل9123456780معcountry_codeبقيمة91)، فلن يُضاف الرمز. أرسل هذه الأرقام متضمنةً رمز الدولة مسبقًا (919123456780). - لا يُتحقق من عناوين URL للصور والملفات عند استدعاء API. فهي تُنزَّل عند إرسال كل رسالة، لذا فإن الرابط المعطّل يجعل الرسائل تفشل لاحقًا بدلًا من أن يفشل الطلب. وتنطبق قواعد وقت الإرسال نفسها المتبعة في إرسال رسالة: تفشل الصور التي يزيد حجمها على 16 MB والفيديوهات التي يزيد حجمها على 64 MB، وملفات الصوت بصيغتي WAV وOGG لا يمكن إرسالها كصورة (
msg_type1)، وتُضاف .pdfإلى الملفات (msg_type2) التي ليس لها امتداد أو لها امتداد غير مدعوم. راجع إرسال الصور والملفات.
حدود الرسائل#
يُتحقق من الدفعة كاملةً قبل إنشاء أي شيء، لذا لا تُرسَل القائمة جزئيًا أبدًا. يُحتسب كل عنصر غير فارغ في phone، بما في ذلك العناصر التي تُتخطّى لاحقًا، وتُحتسب أيضًا الرسائل الموجودة في قائمة الانتظار ولم تُرسَل بعد.
- كل الباقات: يجب أن تتسع الدفعة ضمن حد الاستخدام العادل اليومي لرقم الإرسال – 1,000 رسالة خلال أي 24 ساعة. وإلا فلن تُنشأ أي رسائل وستحصل على:
{
"message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. 1200 messages requested, 640 more can go out from this number in the next 24 hours.",
"code": "daily_limit_reached",
"status": 0
}
- الباقة المجانية: يجب أن تتسع الدفعة أيضًا ضمن الرسائل المجانية المتبقية لمساحة العمل (50 خلال أي 30 يومًا). وإلا ستحصل على:
{
"message": "Not enough credits: 120 messages requested, 35 credits remaining",
"status": 0
}
وزّع القوائم الكبيرة على عدة أرقام أو أيام. وللحملات الكبيرة، ارفع جدول بيانات من صفحة الحملات بدلًا من ذلك.
الاستجابة#
يُرجع الطلب الناجح HTTP 200:
{
"msg_ids": [9817263, 9817264, 9817265],
"messages": [
{ "msg_id": 9817263, "contact": "919876543210", "is_group": false },
{ "msg_id": 9817264, "contact": "919812345670", "is_group": false },
{ "msg_id": 9817265, "contact": "Sales Team Mumbai", "is_group": true }
],
"message": "Successfully created 3 messages",
"status": 1
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 إذا دخلت رسالة واحدة على الأقل قائمة الانتظار، و0 في غير ذلك. |
message | string | Successfully created N messages عند النجاح، وإلا نص الخطأ. |
msg_ids | array of integers | معرّفات الرسائل في قائمة الانتظار، بترتيب phone. يظهر عند النجاح فقط. |
messages | array | كائن واحد لكل رسالة في قائمة الانتظار. يظهر عند النجاح فقط. |
messages[].msg_id | integer | معرّف الرسالة. |
messages[].contact | string | رقم الهاتف بعد تطبيق رمز الدولة، أو اسم المجموعة. |
messages[].is_group | boolean | true إذا عومل العنصر كاسم مجموعة. |
قارن messages بالقائمة التي أرسلتها لمعرفة الأرقام التي تُخطّيت، وتأكد من أن is_group تساوي false لكل عنصر قصدت به رقم هاتف.
الأخطاء#
تُرجع معظم الأخطاء HTTP 200 مع status بقيمة 0، لذا تحقّق دائمًا من status في الجسم. وباستثناء أخطاء HTTP 400 و403، تكون الاستجابات (بما فيها الناجحة) بصيغة JSON لكنها تُرسَل مع Content-Type: text/html، لذا حلّل الجسم بنفسك بدلًا من الاعتماد على الاكتشاف التلقائي لـ JSON (مثلًا في الأدوات بدون برمجة):
{ "message": "Invalid whatsapp client", "status": 0 }
| الرسالة | طريقة الإصلاح |
|---|---|
Auth Error | أرسل client_id وapi_key كليهما. |
Invalid Client Id | أرسل client_id كرقم. يُرجَع مع HTTP 403. |
Auth Error: invalid api key | تأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. يُرجَع مع HTTP 400. |
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. |
Not enough credits: … messages requested, … credits remaining | رسائل الباقة المجانية لا تكفي للقائمة. أرسل إلى عدد أقل من المستلمين أو اختر باقة. راجع حدود الرسائل. |
Daily limit reached: … messages requested, … more can go out from this number in the next 24 hours. | وزّع القائمة على أيام أو أرقام. راجع حدود الرسائل. |
Invalid whatsapp client | معرّف whatsapp_client هذا غير موجود في مساحة العمل الخاصة بك. |
No valid contacts found | كل عنصر في phone كان فارغًا أو تُخطّي. تأكد من أن الأرقام تتكون من 7 إلى 15 رقمًا مع رمز الدولة. |
Demo Account can not access apis | استخدم حسابًا عاديًا. |
Invalid JSON format: … | جسم JSON غير صالح، أو أنك أرسلت حقول نموذج بدون client_id. |
نصائح#
- أرسل
phoneكنص: اجمع قائمتك بالفواصل. مصفوفة JSON تُرجع{}. - لا تستخدم
send_bulk_messagesمن مكتبة Python حاليًا: فهي ترسل القائمة باسمphones، الذي تتجاهله نقطة النهاية هذه. استدعِ نقطة النهاية مباشرةً كما في الأمثلة أعلاه. - تتبّع كل رسالة: احفظ كل
msg_idمنmessages، أو مرّرwebhookليصلك إشعار عند إرسال كل رسالة أو فشلها أو إلغائها أو انتهاء صلاحيتها. - أبقِ رقمك متصلًا: تُرسَل كل رسالة من رقم WhatsApp الخاص بك، لذا يجب أن يبقى متصلًا في إعدادات WhatsApp حتى تُرسَل الدفعة كاملة.
- نص مختلف لكل شخص: ترسل نقطة النهاية هذه
msgنفسها إلى الجميع. استدعِ إرسال رسالة مرة لكل مستلم لتخصيص كل رسالة.

