انتقل إلى المحتوى
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 بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

معاملات الطلب#

المصادقة

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 ‏(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 عند إرسال الرسالة أو فشلها. البيانات المرسلة هي نفسها كما في إرسال رسالة.

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.

صورة من عنوان 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 ولا يرسل إلا إلى المجموعة التي يطابق اسمها 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 نقطة النهاية هذه نيابةً عنك.

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