انتقل إلى المحتوى
Wbiztool

API الرسائل

API إرسال رسالة إلى مجموعة WhatsApp

أرسل نصًا أو صورة أو مستندًا عبر WhatsApp إلى مجموعة WhatsApp يكون رقمك المتصل عضوًا فيها. استخدمه لإعلانات الفريق، وتحديثات المجتمع، والإشعارات العامة.

POSThttps://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."
  }'

استبدل 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 ‏(HTTP 500). راجع كيف يتم العثور على المجموعة.

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.

صورة من عنوان URL
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"
  }'

كيف يتم العثور على المجموعة#

لا يتحقق Wbiztool من اسم المجموعة عند استدعاء API. وعند إرسال الرسالة، يبحث Wbiztool في محادثات WhatsApp الخاصة بك عن group_name ويفتح أول نتيجة. لذلك:

  • يجب أن يكون رقم WhatsApp المتصل عضوًا في المجموعة.
  • استخدم اسم المجموعة الكامل تمامًا كما يعرضه WhatsApp، بما في ذلك الرموز التعبيرية (emoji) وعلامات الترقيم. تُتجاهل المسافات في البداية والنهاية.
  • اجعل الاسم فريدًا. فالاسم القصير أو الجزئي قد يطابق محادثة أخرى تظهر أولًا في البحث.
  • إذا لم يتطابق أي شيء، أو كان إرسال الرسائل في المجموعة مقتصرًا على المشرفين ورقمك ليس مشرفًا، أو كان النشر مقتصرًا على مشرفي المجتمع، فستفشل الرسالة مع الخطأ Group not found.
  • إذا كان رقمك قد غادر المجموعة، فستفشل الرسالة مع الخطأ Group member blocked.

لا تظهر مشكلات المجموعة في استجابة API. استخدم webhook أو حالة الرسالة لمعرفة ما إذا كانت الرسالة قد أُرسلت.

استخدام مكتبة العميل الرسمية#

تستدعي مكتبة Python نقطة النهاية هذه نيابةً عنك.

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
}
الحقلالنوعالوصف
statusinteger‏1 إذا دخلت الرسالة قائمة الانتظار، و0 إذا فشل الطلب.
messagestring‏Created عند النجاح، وإلا نص الخطأ.
msg_idintegerمعرّف الرسالة في قائمة الانتظار. احفظه للتحقق من الحالة لاحقًا. يظهر عند النجاح فقط.

تعني "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 ‏(HTTP 500) بدلًا من JSON.
  • عدة مجموعات دفعة واحدة: يقبل الإرسال إلى عدة أرقام أسماء مجموعات ممزوجة بأرقام هواتف في طلب واحد.