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

API الرسائل

API إرسال رسالة

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

POSThttps://wbiztool.com/api/v1/send_msg/

النص (Body): JSON أو حقول نموذج أو multipart/form-data عند رفع ملف

تدخل الرسالة قائمة الانتظار وتُرسَل من رقم WhatsApp الخاص بك خلال لحظات. تمنحك الاستجابة msg_id يمكنك استخدامه للتحقق من حالتها.

مثال سريع#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -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",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

استبدل 12345 وYOUR_API_KEY و678 بقيمك الخاصة. راجع المصادقة لمعرفة مكان العثور عليها.

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

المصادقة

client_idintegerمطلوب

معرّف العميل في API ‏(API Client ID) من Settings → API keys (الإعدادات ← مفاتيح API).

api_keystringمطلوب

مفتاح API الخاص بك من الصفحة نفسها.

whatsapp_clientintegerمطلوب إذا كان لديك أكثر من رقم

معرّف رقم WhatsApp الذي ستُرسَل منه الرسالة، من إعدادات WhatsApp. إذا حذفته وكان في مساحة العمل الخاصة بك رقم متصل واحد فقط، فسيُستخدم ذلك الرقم.

المستلم والرسالة

phonestringمطلوب

رقم WhatsApp الخاص بالمستلم، أرقام فقط. تُزال المسافات و+ و- و. والأقواس تلقائيًا. أرسل الرقم إمّا مع رمز الدولة (919876543210) أو بدونه (9876543210) مع country_code. مع حقول النموذج، لا تضع الصفر البادئ (trunk 0) في أول الرقم (09876543210): فهو لا يُزال قبل إضافة country_code، فتذهب الرسالة إلى رقم خاطئ. أما طلبات JSON فتُزيله تلقائيًا.

country_codestringاختياري

رمز الاتصال الدولي للدولة بدون +، مثل 91 للهند أو 1 للولايات المتحدة. يُضاف قبل phone إلا إذا كان الرقم يبدأ به بالفعل. استثناء: مع 91، يحصل الرقم المكوّن من 10 أرقام على البادئة دائمًا. ومع الرموز الأخرى، لا تُضاف البادئة إلى الرقم المحلي الذي يبدأ بالأرقام نفسها، لذا أرسله متضمنًا رمز الدولة.

msg_typeintegerاختياري

‏0 نص (افتراضي)، و1 صورة، و2 ملف أو مستند.

msgstringمطلوب عندما تكون قيمة msg_type هي 0

نص الرسالة، حتى 3,000 حرف. للصور والملفات يكون هو التعليق (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اختياري

اسم الملف الذي يراه المستلم، مثل invoice-4821.pdf. امتداده هو الذي يحدّد طريقة إرسال الملف، لذا ضع امتدادًا. يُرسَل بأحرف صغيرة، وتُستبدل أحرف مثل & : ? * $ ; بـ _، ويُقتطع عند 150 حرفًا. إذا حذفته، يُؤخذ الاسم من عنوان URL أو من الملف المرفوع.

خيارات الإرسال

expire_after_secondsintegerاختياري

يحدّد الرسالة على أنها منتهية الصلاحية (الحالة 4) إذا لم تُرسَل خلال هذا العدد من الثواني، مثل 3600 لساعة واحدة. مفيد للرسائل الحساسة للوقت مثل مواعيد التوصيل المتوقعة. تنفّذ ذلك مهمة في الخلفية بعد 30 ثانية على الأقل من انتهاء المهلة، لذا لا تعتمد عليه في مهل أقصر من دقيقة.

webhookstringاختياري

عنوان URL يستقبل طلب POST عند إرسال الرسالة أو فشلها. راجع Webhook.

إرسال الصور والملفات#

حدود التنزيل لـ img_url وfile_url:

  • يجب أن يكون عنوان URL عامًا: يبدأ بـ http أو https ويمكن الوصول إليه من الإنترنت. تُتبَع 5 عمليات إعادة توجيه كحد أقصى، ويجب أن تؤدي كل واحدة منها أيضًا إلى عنوان عام.
  • يمكن أن يصل حجم الملفات المرتبطة إلى 100 MB. يجب أن يبدأ الخادم بالاستجابة خلال 45 ثانية، وألا يتوقف لمدة أطول من ذلك.
  • يُجلب الملف عند استدعاء API، لذا يفشل الرابط المعطّل فورًا مع Invalid file url.

الامتدادات المدعومة: .pdf، .xlsx، .xls، .txt، .docx، .png، .jpg، .jpeg، .webp، .mp3، .mpga، .m4a، .mp4، .webm.

تُجرى هذه الفحوص عند إرسال الرسالة، لا عند استدعاء API، لذا لا تظهر حالات الفشل إلا في حالة الرسالة وفي webhook:

المشكلةقيمة error في حالة الرسالة
صورة (msg_type 1) يزيد حجمها على 16 MBFile exceeds WhatsApp size limit (16MB max)
فيديو (.mp4، .webm) يزيد حجمه على 64 MB، أو ملف فارغFile exceeds WhatsApp size limit (…)
ملف .ogg، أو ملف .wav مُرسَل كصورة (msg_type 1)File type not supported

ملفات الصوت بصيغتي WAV وOGG غير مدعومة. ملف .wav المُرسَل كملف (msg_type 2) لا يُرفض، لكنه يصل باسم recording.wav.pdf. حوّل الصوت إلى .mp3 أو .m4a أولًا.

صورة من عنوان URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -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",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
رفع ملف
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

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

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

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id="12345")

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    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 (لا يحتوي Account Disabled على الحقل status):

{ "status": 0, "message": "Msg 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 هذا.
Either phone or group_name parameter is requiredأضف phone.
Please provide either phone OR group_name, not bothاحذف أحدهما.
Invalid phone numberيجب أن يحتوي phone على أرقام فقط (من 6 إلى 17 رقمًا)، ويمكن أن يبدأ بـ +.
Invalid Contact Number "…"بعد إضافة رمز الدولة، يجب أن يتكون الرقم من 6 إلى 15 رقمًا.
Msg cant be nullالرسائل النصية (msg_type 0) تحتاج إلى msg.
Message length is too longاجعل msg في حدود 3,000 حرف أو أقل.
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معرّف 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 للأسطر الجديدة.

قد تفشل الرسالة الموجودة في قائمة الانتظار عند إرسالها رغم ذلك، مثلًا مع File exceeds WhatsApp size limit (…). هذه الأخطاء لا تظهر أبدًا في هذه الاستجابة. راجع إرسال الصور والملفات وتحقّق من حالة الرسالة.

Webhook#

إذا مرّرت webhook، يرسل Wbiztool طلب POST إلى عنوان URL هذا عند إرسال الرسالة أو فشلها. يكون الجسم مرمّزًا كنموذج (application/x-www-form-urlencoded)، وليس JSON:

msg_id=9817263&status=SENT
الحقلالقيم
msg_idقيمة msg_id التي أُرجعت عند إرسال الرسالة.
status‏SENT أو FAILED

استجب بأي رمز 2xx. إذا انتهت مهلة نقطة النهاية لديك (بعد 3 ثوانٍ) أو أرجعت 5xx، يُعاد الاستدعاء حتى 3 مرات إجمالًا. لا يُعاد الاستدعاء عند استجابة 4xx. لا يُرسَل أي webhook عند إلغاء رسالة أو انتهاء صلاحيتها؛ استخدم حالة الرسالة لهذه الحالات.

نصائح#

  • أرقام الهواتف: خزّن الأرقام بالصيغة الدولية وأرسلها مع country_code لتجنّب الالتباس.
  • الأسطر الجديدة في JSON: اكتبها بالشكل \n داخل msg. السطر الجديد الخام يجعل JSON غير صالح.
  • أبقِ رقمك متصلًا: تُرسَل الرسائل من رقم WhatsApp الخاص بك، لذا يجب أن يبقى متصلًا في إعدادات WhatsApp.
  • مستلمون كثيرون: لإرسال الرسالة نفسها إلى عدة أرقام في طلب واحد، استخدم الإرسال إلى عدة أرقام. وللحملات الكبيرة، ارفع جدول بيانات من صفحة الحملات بدلًا من ذلك.