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 بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.
معاملات الطلب#
المصادقة
client_idintegerمطلوبمعرّف العميل في API (API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).
api_keystringمطلوبمفتاح API الخاص بك من الصفحة نفسها.
whatsapp_clientintegerمطلوب إذا كان لدى المالك أكثر من رقم متصلمعرّف رقم WhatsApp الذي ستُرسَل منه الرسالة، من إعدادات 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عند إرسال الرسالة أو فشلها. البيانات المرسلة هي نفسها كما في إرسال رسالة.
تخضع الصور والملفات للقواعد نفسها المتبعة في إرسال رسالة: تُنزَّل عناوين URL عند استدعاء API (حتى 100 MB). وعند إرسال الرسالة، تفشل الصور التي يزيد حجمها على 16 MB والفيديوهات التي يزيد حجمها على 64 MB، وملفات الصوت بصيغتي WAV وOGG غير مدعومة، ويُضاف .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 ويفتح أول نتيجة. لذلك:
- يجب أن يكون رقم WhatsApp المتصل عضوًا في المجموعة.
- استخدم اسم المجموعة الكامل تمامًا كما يعرضه WhatsApp، بما في ذلك الرموز التعبيرية (emoji) وعلامات الترقيم. تُتجاهل المسافات في البداية والنهاية.
- اجعل الاسم فريدًا. فالاسم القصير أو الجزئي قد يطابق محادثة أخرى تظهر أولًا في البحث.
- إذا لم يتطابق أي شيء، أو كان إرسال الرسائل في المجموعة مقتصرًا على المشرفين ورقمك ليس مشرفًا، أو كان النشر مقتصرًا على مشرفي المجتمع، فستفشل الرسالة مع الخطأ
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 None | معرّف whatsapp_client هذا لا يخص مالك مساحة العمل. راجع التحذير أعلاه. |
Invalid whatsapp client id. | أرسل whatsapp_client. فهو مطلوب ما لم يكن لدى المالك رقم متصل واحد فقط. |
Not enough credits | لم يتبقَّ في باقتك أي رسائل. |
Demo Account can not access apis | استخدم حسابًا عاديًا. |
Account Disabled | حسابك معطّل. تواصل مع الدعم. |
Invalid JSON format: … | جسم JSON غير صالح، وغالبًا بسبب فاصلة زائدة في النهاية أو سطر جديد غير مُهرَّب داخل msg. استخدم \n للأسطر الجديدة. |
نصائح#
- اختبر الاسم أولًا: أرسل نصًا قصيرًا إلى المجموعة وتحقّق من حالة الرسالة قبل أن تؤتمت أي شيء.
- المجموعات التي تغيّر اسمها: إذا غيّر أحدهم اسم المجموعة في WhatsApp، فحدّث
group_nameفي تكاملك أيضًا. - أنواع الرسائل: القيم الصالحة لـ
msg_typeهي0و1و2فقط. وأي قيمة ليست عددًا صحيحًا تُرجع صفحة خطأ بصيغة HTML (HTTP500) بدلًا من JSON. - عدة مجموعات دفعة واحدة: يقبل الإرسال إلى عدة أرقام أسماء مجموعات ممزوجة بأرقام هواتف في طلب واحد.
