API الرسائل
API إرسال رسالة إلى مجموعة WhatsApp
أرسل نصًا أو صورة أو مستندًا عبر WhatsApp إلى مجموعة WhatsApp يكون رقمك المتصل عضوًا فيها. استخدمه لإعلانات الفريق، وتحديثات المجتمع، والإشعارات العامة.
https://wbiztool.com/api/v1/send_msg/group/النص (Body): JSON أو حقول نموذج أو multipart/form-data عند رفع ملف
تدخل الرسالة قائمة الانتظار وتُرسَل إلى المجموعة من رقم WhatsApp الخاص بك. تمنحك الاستجابة msg_id يمكنك استخدامه للتحقق من حالتها.
مثال سريع#
curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
-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": "Reminder: *weekly review* starts at 4 PM today."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/group/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 0,
"group_name": "Sales Team Mumbai",
"msg": "Reminder: *weekly review* starts at 4 PM today.",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Queued with msg_id", result["msg_id"])
else:
print("Failed:", result.get("message"))// 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/group/", {
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: "Reminder: *weekly review* starts at 4 PM today.",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Queued with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message);
}<?php
$payload = [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 0,
'group_name' => 'Sales Team Mumbai',
'msg' => 'Reminder: *weekly review* starts at 4 PM today.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/group/');
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 'Queued with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no 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 الذي ستُرسَل منه الرسالة، من إعدادات WhatsApp. يصلح أي رقم في مساحة العمل الخاصة بك، أيًّا كان عضو الفريق الذي ربطه. إذا حذفته وكانت مساحة العمل تضم رقم WhatsApp متصلًا واحدًا فقط، فسيُستخدم ذلك الرقم (أو حساب Telegram الوحيد، عندما لا يكون أي رقم WhatsApp متصلًا).
المجموعة والرسالة
group_namestringمطلوباسم مجموعة WhatsApp، مكتوبًا تمامًا كما يظهر في WhatsApp. أرسله كنص. الرقم في JSON مثل
2024يُرجع صفحة خطأ بصيغة HTML (HTTP500). راجع كيف يتم العثور على المجموعة.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ويمكن تنزيل الملف منه مباشرةً.filefileاختياريارفع الصورة أو الملف بدلًا من تقديم عنوان URL. أرسل الطلب بصيغة
multipart/form-dataمع حقل باسمfile.file_namestringاختيارياسم الملف الذي تراه المجموعة، مثل
price-list.pdf. امتداده هو الذي يحدّد طريقة إرسال الملف، لذا ضع امتدادًا. يُرسَل بأحرف صغيرة، وتُستبدل أحرف مثل& : ? * $ ;بـ_، ويُقتطع عند 150 حرفًا. إذا حذفته، يُؤخذ الاسم من عنوان URL أو من الملف المرفوع.
خيارات الإرسال
expire_after_secondsintegerاختيارييحدّد الرسالة على أنها منتهية الصلاحية (الحالة
4) إذا لم تُرسَل خلال هذا العدد من الثواني، مثل3600لساعة واحدة. تنفّذ ذلك مهمة في الخلفية بعد 30 ثانية على الأقل من انتهاء المهلة، لذا لا تعتمد عليه في مهل أقصر من دقيقة.webhookstringاختياريعنوان URL يستقبل طلب
POSTعند إرسال الرسالة أو فشلها. البيانات المرسلة هي نفسها كما في إرسال رسالة.idempotency_keystringاختيارياختياري، حتى 255 حرفًا. لمدة 24 ساعة، إذا أعدت المحاولة بالقيمة نفسها تحصل على الاستجابة الأولى بدلًا من رسالة ثانية. ويمكنك إرساله بدلًا من ذلك في ترويسة
Idempotency-Key. راجع إعادة المحاولة بأمان.
تخضع الصور والملفات للقواعد نفسها المتبعة في إرسال رسالة: تُنزَّل عناوين URL عند استدعاء API (حتى 100 MB). وعند إرسال الرسالة، تفشل الصور التي يزيد حجمها على 16 MB والفيديوهات التي يزيد حجمها على 64 MB، وملفات الصوت بصيغتي WAV وOGG لا يمكن إرسالها كصورة (msg_type 1)، وتُضاف .pdf إلى الملفات (msg_type 2) التي ليس لها امتداد أو لها امتداد غير مدعوم، بما في ذلك الملفات المرفوعة. تُرسَل أسماء الملفات بأحرف صغيرة. راجع إرسال الصور والملفات للاطلاع على القائمة الكاملة للامتدادات والأخطاء.
لرفع ملف، استخدم أمثلة multipart في إرسال رسالة، مع استبدال عنوان URL بـ /api/v1/send_msg/group/ واستبدال phone/country_code بـ group_name.
curl -X POST https://wbiztool.com/api/v1/send_msg/group/ \
-H "Content-Type: application/json" \
-d '{
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 1,
"group_name": "Sales Team Mumbai",
"img_url": "https://example.com/reports/weekly-sales.png",
"msg": "This week'\''s sales summary"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/group/",
json={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 1,
"group_name": "Sales Team Mumbai",
"img_url": "https://example.com/reports/weekly-sales.png",
"msg": "This week's sales summary",
},
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/send_msg/group/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
client_id: 12345,
api_key: "YOUR_API_KEY",
whatsapp_client: 678,
msg_type: 1,
group_name: "Sales Team Mumbai",
img_url: "https://example.com/reports/weekly-sales.png",
msg: "This week's sales summary",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/group/');
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' => 1,
'group_name' => 'Sales Team Mumbai',
'img_url' => 'https://example.com/reports/weekly-sales.png',
'msg' => "This week's sales summary",
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);كيف يتم العثور على المجموعة#
لا يتحقق WbizTool من اسم المجموعة عند استدعاء API. وعند إرسال الرسالة، يبحث WbizTool في محادثات WhatsApp الخاصة بك عن group_name ولا يرسل إلا إلى المجموعة التي يطابق اسمها group_name تمامًا. لذلك:
- يجب أن يكون رقم WhatsApp المتصل عضوًا في المجموعة.
- استخدم اسم المجموعة الدقيق كما يعرضه WhatsApp، بما في ذلك الرموز التعبيرية (emoji) وعلامات الترقيم. تُتجاهل المسافات في البداية والنهاية، وتُحسب المسافات المتتالية مسافةً واحدة.
- لم تعد الأسماء الجزئية تطابق. فالاسم
Sales Teamلا يرسل إلىSales Team Mumbai، حتى لو كانت هذه المجموعة أول نتيجة في البحث. - اكتب الأحرف الكبيرة والصغيرة كما يعرضها WhatsApp. الاسم الذي يختلف فقط في حالة الأحرف، مثل
sales team mumbai، لا يُقبل إلا إذا لم تكن هناك محادثة بالكتابة الدقيقة نفسها وكانت كتابة واحدة فقط هي المطابقة. - لا تُسمِّ جهة اتصال باسم مجموعة. إذا كانت لديك في WhatsApp جهة اتصال بهذا الاسم، أو كانت جهة اتصال ومجموعة تتشاركان الاسم، فلن تُرسل الرسالة. غيّر اسم جهة الاتصال أو المجموعة.
- إذا كان لمجموعتين الاسم نفسه تمامًا، فستُرسل الرسالة إلى أولاهما في نتائج بحث WhatsApp. امنح كل مجموعة اسمًا فريدًا.
- إذا لم تكن هناك مجموعة بهذا الاسم تمامًا، أو كان الاسم لجهة اتصال، أو كان إرسال الرسائل في المجموعة مقتصرًا على المشرفين ورقمك ليس مشرفًا، أو كان النشر مقتصرًا على مشرفي المجتمع، فستفشل الرسالة مع الخطأ
Group not found. - إذا كان رقمك قد غادر المجموعة، فستفشل الرسالة مع الخطأ
Group member blocked.
لا تظهر مشكلات المجموعة في استجابة API. استخدم webhook أو حالة الرسالة لمعرفة ما إذا كانت الرسالة قد أُرسلت.
استخدام مكتبة العميل الرسمية#
تستدعي مكتبة Python نقطة النهاية هذه نيابةً عنك.
from wbiztool_client import WbizToolClient
client = WbizToolClient(api_key="YOUR_API_KEY", client_id=12345)
result = client.send_message_to_group(
group_name="Sales Team Mumbai",
msg="Reminder: weekly review starts at 4 PM today.",
whatsapp_client=678,
)
print(result)تُطلق الأخطاء الاستثناء requests.HTTPError. اقرأ السبب باستخدام e.response.json()["message"].
الاستجابة#
يُرجع الطلب الناجح HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| الحقل | النوع | الوصف |
|---|---|---|
status | integer | 1 إذا دخلت الرسالة قائمة الانتظار، و0 إذا فشل الطلب. |
message | string | Created عند النجاح، وإلا نص الخطأ. |
msg_id | integer | معرّف الرسالة في قائمة الانتظار. احفظه للتحقق من الحالة لاحقًا. يظهر عند النجاح فقط. |
تعني "status": 1 أن الرسالة دخلت قائمة الانتظار، لا أنها وصلت إلى المجموعة. استخدم webhook أو حالة الرسالة للتأكد من إرسالها.
الأخطاء#
تُرجع الأخطاء HTTP 400 مع status بقيمة 0:
{ "status": 0, "message": "Group Name cant be null" }
| الرسالة | طريقة الإصلاح |
|---|---|
Auth Error - Please send correct API key and Client id | أرسل api_key غير فارغ. |
Invalid client id. | أرسل client_id كرقم. |
Auth Error: invalid api key | تأكد من أن المفتاح موجود، ولم يُحذف، وينتمي إلى client_id هذا. |
Group Name cant be null | أضف group_name. |
Msg cant be null | الرسائل النصية (msg_type 0) تحتاج إلى msg. |
Image Url Can't be null | مع msg_type 1، أرسل img_url أو ارفع file. |
File Url Can't be null | مع msg_type 2، أرسل file_url أو ارفع file. |
Invalid file url, Can't download / Invalid file url | عنوان URL ليس عامًا، أو انتهت مهلته، أو أن حجم الملف يزيد على 100 MB. |
Invalid whatsapp client <id>: this WhatsApp number was deleted or does not belong to your account… | رقم whatsapp_client هذا محذوف أو لا ينتمي إلى مساحة العمل التابع لها مفتاح API. استخدم معرّف رقم متصل من إعدادات WhatsApp. |
Invalid whatsapp client id. | أرسل whatsapp_client. فهو مطلوب ما لم تكن مساحة العمل الخاصة بك تضم رقمًا متصلًا واحدًا فقط. |
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 | استخدم حسابًا عاديًا. |
Account Disabled | حسابك معطّل. تواصل مع الدعم. |
Invalid JSON format: … | جسم JSON غير صالح، وغالبًا بسبب فاصلة زائدة في النهاية أو سطر جديد غير مُهرَّب داخل msg. استخدم \n للأسطر الجديدة. |
نصائح#
- اختبر الاسم أولًا: أرسل نصًا قصيرًا إلى المجموعة وتحقّق من حالة الرسالة قبل أن تؤتمت أي شيء. إذا فشلت مع
Group not found، فراجع كيف يتم العثور على المجموعة. - المجموعات التي تغيّر اسمها: إذا غيّر أحدهم اسم المجموعة في WhatsApp، فحدّث
group_nameفي تكاملك أيضًا. - أنواع الرسائل: القيم الصالحة لـ
msg_typeهي0و1و2فقط. وأي قيمة ليست عددًا صحيحًا تُرجع صفحة خطأ بصيغة HTML (HTTP500) بدلًا من JSON. - عدة مجموعات دفعة واحدة: يقبل الإرسال إلى عدة أرقام أسماء مجموعات ممزوجة بأرقام هواتف في طلب واحد.

